Documentation/DevGuide/Basic/Accessing Libraries from Basic

OpenOffice Developer's Guide

OpenOffice Basic

< Previous Section

Next Section >

• First Steps with OpenOffice Basic

• Creating a Module in a Standard Library
• Writing and Debugging a Basic UNO program
• Calling a Sub from the User Interface
• Creating Dialogs
• Adding Event Handlers
• AutoPilot Dialogs

• OpenOffice Basic IDE

• Managing Basic and Dialog Libraries

• OpenOffice Basic Macros Dialog

• Displayed Information
• Buttons

• OpenOffice Basic Macro Organizer Dialog

• Modules
• Dialogs
• Libraries

• Basic IDE Window

• Basic Source Editor and Debugger
• Dialog Editor

• Assigning Macros to GUI Events
• Dialog Localization

• Technical Background

• Features of OpenOffice Basic

• Functional Range Overview

• Screen I/O Functions
• File I/O
• Date and Time Functions
• Numeric Functions
• String Functions
• Specific UNO Functions

• Accessing the UNO API
• Special Behavior of OpenOffice Basic

• Advanced Library Organization

• General Structure
• Accessing Libraries from Basic
• Variable Scopes

• Programming Dialogs and Dialog Controls

• Dialog Handling

• Showing a Dialog
• Getting the Dialog Model
• Dialog as Control Container
• Dialog Properties
• Common Properties
• Multi-Page Dialogs

• Dialog Controls

• Command Button
• Image Control
• Check Box
• Option Button
• Label Field
• Text Field
• List Box
• Combo Box
• Horizontal/Vertical Scroll Bar
• Group Box
• Progress Bar
• Horizontal/Vertical Line
• Date Field
• Time Field
• Numeric Field
• Currency Field
• Formatted Field
• Pattern Field
• File Control

• Creating Dialogs at Runtime
• Library File Structure

• Application Library Container
• Document Library Container

• Library Deployment

< Previous Page

Next Page >

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 and DialogLibraries.

The 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 DialogLibraries property.

Loading Libraries

Initially, most Basic libraries are not loaded. All the libraries in the application library container are known after starting Apache OpenOffice, 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 doSomething():

  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.

The properties BasicLibraries and DialogLibraries refer to the container that includes the Basic source accessing these properties. Therefore in a document module Basic the properties BasicLibraries and 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 GlobalScope.

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

The BasicLibraries and 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.

The 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)

The 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 Apache OpenOffice 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 createLibraryLink(). Its StorageURL parameter 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 StorageURL parameter.

The ReadOnly parameter 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
isLibraryLink()	boolean. Can be used to ask if a library was added to the library container as a link.
getLibraryLinkURL()	string. Returns the StorageURL for a linked library. This corresponds to the StorageURL parameter of the createLibraryLink(...) method and is primarily meant to be displayed to the users through the graphical user interface.
isLibraryReadOnly()	boolean. Retrieves the read-only status of a library. In case of a library link, the method returns only false, that is, the library can be modified, when the link or the linked library are not read only.
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
loadLibrary()	void. Loads a library. This is explained in detail in section Advanced Library Organization
isLibraryLoaded()	boolean. Allows the user to find out if a library has already been loaded.
removeLibrary()	void. Removes the library from the library container. If the library was added to the library container as a link, only the link is removed, because the library addressed by the link is not considered to be owned by the library container.

Content on this page is licensed under the Public Documentation License (PDL).