I packaged some of the macros that I use into an application-level library with the name "Pitonyak." The next day, I started OpenOffice.org, and to my surprise, I was not able to use any macros in my new library. It turns out that libraries must be loaded before they are available.
Tip | A library must be loaded before it is available. |
To manually load a library, open the Macro Organizer dialog (Tools Macros Macro) and double-click the library that you want to load.
You can also access libraries by using a macro. OOo Basic provides the variable GlobalScope to manipulate application-level libraries (see Listing 1 ).
GlobalScope.BasicLibraries.loadLibrary("Pitonyak")
Tip | The GlobalScope variable does not support the "dbg" properties. In other words, you cannot inspect the GlobalScope variable. |
Libraries contain two things-dialogs and macros. The GlobalScope variable has two properties-BasicLibraries and DialogLibraries-that provide access to the Basic and dialog library containers in the application library container. The BasicLibraries and DialogLibraries properties both support the same set of interfaces for accessing the contained library containers (see Table 1 ).
Method | Description |
---|---|
createLibrary(Name) | Create a new library with the given name. |
createLibraryLink(Name, Url, ReadOnly) | Create a link to an "external" library. The Name and URL are both strings. If the ReadOnly flag is True, the library cannot be modified. |
removeLibrary(Name) | Remove the named library. If the library is a link, only the link is removed, not the actual library. |
isLibraryLoaded(Name) | True if the library is loaded, False otherwise . |
loadLibrary(Name) | Load a library if it is not already loaded. |
isLibraryLink(Name) | True if the library is a link to another library. |
getLibraryLinkURL(Name) | Return the URL of a linked library. An error occurs if the library is not a link. |
isLibraryReadOnly(Name) | Return True if the library is read-only. |
setLibraryReadOnly(Name, ReadOnly) | Set the named library to read-only if Readonly is True. |
renameLibrary(Name, NewName) | Rename a library. If the library is linked, only the link is renamed . |
changeLibraryPassword(Name, Pass, NewPass) | Change a library's password. |
getByName(Name) | Get the named library. |
getElementNames() | Get an array of library names . |
hasByName(Name) | True, if the named library exists. |
hasElements() | True, if at least one library exists. |
isLibraryPasswordProtected(Name) | True, if the library is password protected. |
isLibraryPasswordVerified(Name) | True, if the password has already been used to unlock a library. |
verifyLibraryPassword(Name, Pass) | Unlock a password-protected library. |
Tip | The GlobalScope variable is not available outside of OOo Basic. It is, however, possible to create and use the undocumented UNO service com.sun.star.script.ApplicationScriptLibraryContainer to access the global Basic libraries. |
The contained libraries are stored as XML strings inside named containers. Table 2 contains the methods supported by library objects.
Method | Description |
---|---|
getByName(Name) | Get the named module as a String. |
getElementNames() | Get an array of module names. |
hasByName(Name) | True, if the library contains the named module. |
hasElements() | True, if the library contains at least one module. |
insertByName(Name, Module) | Insert the named module into the library. |
removeByName(Name) | Remove the named module. |
replaceByName(Name, Module) | Replace the named module. |
When you use the macro organizer to create a library, it automatically creates both a dialog library and a Basic library. The newly created Basic library contains the module named "Module 1," which contains an empty subroutine named "Main." The following steps illustrate the process:
Open the Macro dialog using Tools Macros Macro.
Click the Organizer button to open the Macro Organizer dialog.
Click the Library tab.
Click the New button and give the library the name "TestLib" (see Figure 1 ).
Figure 1: Creating a new library in the "soffice" aplication library container.
Click OK to close the New Library dialog.
Click the Close button on the Macro Organizer dialog.
Click the Close button on the Macro dialog.
To seethe contents of the TestLib library, enter and run the macro in Listing 2 . As seen in Figure 2 . Module 1 contains a module with a single subroutine.
Dim oLib oLib = GlobalScope.BasicLibraries.getByName("TestLib") MsgBox oLib.getByName("Module1"), 0, "Modulel in TestLib"
You can use the code in Listing 3 to verify that both a Basic and a dialog library exist. Although the dialog library exists, it does not contain any dialogs. If the TestLib library does not exist, the returned library is null.
oLib = GlobalScope.BasicLibraries.getByName("TestLib") oLib = GlobalScope.DialogLibraries.getByName("TestLib")
Tip | Libraries created using the methods in Table 2 do not automatically create both a dialog and a macro dialog. |
Libraries created using the UNO API in Table 2 cause only one library to be created. The macro in Listing 4 creates a dialog library and a corresponding Basic library, adds Module1 to the code library, and adds a subroutine to Module1. See Figure 3 .
Sub CreateAGlobalLib Dim oLib Dim s$ If GlobalScope.BasicLibraries.hasByName("TestLib") Then GlobalScope.BasicLibraries.removeLibrary("TestLib") GlobalScope.DialogLibraries.removeLibrary("TestLib") MsgBox "Deleted TestLib" Else GlobalScope.BasicLibraries.createLibrary("TestLib") GlobalScope.DialogLibraries.createLibrary("TestLib") oLib = GlobalScope.BasicLibraries.getByName("TestLib") s = "Sub Main" & CHR$(10) &_ " x = x + 1" & CHR$(10) &_ "End Sub" oLib.insertByName("Module1", s) s = "=== Basic Libs ===" & CHR$(10) oLib = GlobalScope.BasicLibraries.getByName("TestLib") s = s & Join(oLib.getElementNames(), CHR$(10)) oLib = GlobalScope.DialogLibraries.getByName("TestLib") s = s & CHR$(10) & CHR$(10) & "=== Dialog Libs ===" & CHR$(10) s = s & Join(oLib.getElementNames(), CHR$(10)) MsgBox s, 0, "Modules in the PitonyakDialogs Library" oLib = GlobalScope.BasicLibraries.getByName("TestLib") MsgBox oLib.getByName("Module1"), 0, "Module1 in TestLib" End If End Sub