Custom OpenOffice.org Basic Macros and Libraries

From Apache OpenOffice Wiki
Jump to: navigation, search


OpenOffice.org Basic is a programming language you can use to automate tasks in OpenOffice.org. OpenOffice.org Basic macros are stored in modules that in turn are stored in libraries. Libraries also act as containers for dialog boxes you create in OpenOffice.org Basic. You can store Basic libraries in any directory that a user can access.

Documentation note.png Use OpenOffice.org extensions for packaging and deploying Basic Libraries. The OpenOffice.org Developer's Guide describes these Extensions in detail.

About OpenOffice.org Basic Libraries and Modules

The default OpenOffice.org Basic libraries are located in the install-dir/share/basic directory. A library contains the following files:

script.xlb
An XML file that contains the names of the modules in the library.
dialog.xlb
An XML file that contains the names of dialog boxes in the library.
*.xba
An XML file that stores the OpenOffice.org Basic source code for a single OpenOffice.org Basic module. The file name corresponds to the module name.
*.xdl
An XML file that stores the dialog elements of an OpenOffice.org Basic dialog box. The file name corresponds to the dialog name.
*.pba
An OpenOffice.org Basic module which is protected with a password, that is, the source code is encrypted. The file name corresponds to the module name.

About OpenOffice.org Basic Configuration Files

The script.xlc and dialog.xlc configuration files list the location of OpenOffice.org Basic libraries and dialog boxes. These files are located in the install-dir/user/basic/ directory which also contains the default Standard OpenOffice.org Basic library as well as the user-defined libraries.

Documentation caution.png

You cannot change the location of the script.xlc and dialog.xlc configuration files.


The XML-based script.xlc file includes a list of all Basic libraries that are available to OpenOffice.org. The following tags are used:

library:name
Specifies the name of the OpenOffice.org Basic library.
xlink:href
Specifies the URL of the script.xlb file for the library. The URL must begin with the file:/// notation.
Documentation note.png You do not need to specify a value for the xlink:href tag if the library is in the <OpenOffice.org installation directory>/user/basic directory.
xlink:type
This tag, required by the xlink:href tag, must be set to simple.
library:link
Specifies that the entry is a link to a library that is not in the default library location. The default location for OpenOffice.org Basic libraries is install-dir/user/basic. If you only use the default location for the libraries, set the value of this tag to false. For all other libraries, set the value of this tag to true.
library:readonly
Specifies whether a library is read-only. Set the value of this tag to true for read-only access.

The following XML code is for a script.xlc configuration file for OpenOffice.org Basic libraries. The only difference between this file and a dialog.xlc file is that the xlink:href tag points to the script.xlb file of a library instead of the dialog.xlb file.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE library:libraries PUBLIC 
"-//OpenOffice.org//DTD OfficeDocument 1.0//EN" "libraries.dtd">
 
<library:libraries 
xmlns:library="http://openoffice.org/2000/library" 
xmlns:xlink="http://www.w3.org/1999/xlink">
 
<library:library library:name="Standard" 
xlink:href="file:///.../user/basic/Standard/script.xlb/" 
xlink:type="simple" library:link="false"/>
 
<library:library library:name="FormWizard" 
xlink:href="file:///.../share/basic/FormWizard/script.xlb/" 
xlink:type="simple" library:link="true" library:readonly="false"/>
</library:libraries>

Sample OpenOffice.org Basic Configuration File

Distributing OpenOffice.org Basic Libraries

You can make custom OpenOffice.org Basic libraries available to either existing OpenOffice.org installations or new installations only.

Documentation note.png The script.xlc and dialog.xlc configuration files are located in the following directories:
  • Solaris and Linux platforms: install-dir/usr/basic/
  • Windows: C:\Documents and Settings\user-id\Application Data\install-dir\user\basic\

To Make a Custom OpenOffice.org Basic Library Available to All Users on a Network

Use OpenOffice.org to create a custom library as well as the macros in the library.

  1. As root, copy the custom library from the user installation where you created the library to the OpenOffice.org server installation.
    cp -r install-dir/user/basic/custom library install-dir/share/basic/
    Documentation note.png On Windows, the location of the custom library you created is C:\Documents and Settings\user-id\Application Data\installation-dir\user\basic\custom library
  2. In the script.xlc configuration file for the user installation, add a link to the script.xlb configuration file for the library.
    Use the following syntax for the link:
     <library:library library:name="Library Name"
     xlink:href="$(USER)/basic/Library Name/script.xlb/"
     xlink:type="simple" library:link="true" library:readonly="false"/>
  3. In the dialog.xlc configuration file for the user installation, add a link to the script.xlb configuration file for the library.
    Use the following syntax for the link:
     <library:library library:name="Library Name"
     xlink:href="$(USER)/basic/Library Name/dialog.xlb/"
     xlink:type="simple" library:link="false"/>
  4. Restart OpenOffice.org on the workstations.

To Make a Custom OpenOffice.org Basic Library Available to a Single User

  1. Copy the custom library from the user installation where you created the library to the user installation where you want to deploy the library.
    • On the Solaris and Linux platforms, become root, and copy the library.
    cp -r ''install-dir''/user/basic/custom library ''install-dir''/user/basic/
    • On Windows, become a user with administrator privileges, and copy the library.

    The file name path for the library is C:\Documents and Settings\user-id\Application Data\install-dir\user\basic\custom library

  2. In the script.xlc configuration file for the user installation, add a link to the script.xlb configuration file for the library.
    Use the following syntax for the link:
     <library:library library:name="Library Name"
     xlink:href="$(USER)/basic/Library Name/script.xlb/"
     xlink:type="simple" library:link="true" library:readonly="false"/>
  3. In the dialog.xlc configuration file for the user installation, add a link to the script.xlb configuration file for the library.
    Use the following syntax for the link:
     <library:library library:name="Library Name"
     xlink:href="$(USER)/basic/Library Name/dialog.xlb/"
     xlink:type="simple" library:link="false"/>
  4. Restart OpenOffice.org.

To Install a Custom OpenOffice.org Basic Library With a Macro

You can create a macro that installs a OpenOffice.org Basic library from an OpenOffice.org document.

  1. In Writer, create a custom OpenOffice.org Basic library in a new document.
  2. Save the document.
  3. Create an installation macro.
    1. Choose Tools → Macros → Organize Macros → OpenOffice.org Basic. The OpenOffice.org Basic Macros dialog box appears.
    2. In the Macro from list, select your Writer document.
    3. In the Macro name box, type a name from the installation macro.
    4. Click the New button. The BASIC IDE window appears.
    5. Type the following code:
    6.  Sub AddBasicLibrary
        Dim SourceLibraryName As String, DestLibraryName As String
        Dim oSrcLib As Object, oDestLib As Object, iCounter As Integer
        Dim oLib As Object, oGlobalLib As Object
       
        ' set these 2 variables to your lib name
        SrcLibraryName = "TextLib" 
        ' The name of the library that contains the modules
        DestLibraryName = "NewLib" 
        ' This library will be created and is the 
        ' destination for the modules from the source document.
       
        oLib = BasicLibraries        ' For Basic libaries
        oGlobalLib = GlobalScope.BasicLibraries
        For iLib = 1 To 2 
          If oGlobalLib.hasByName( DestLibraryName ) = False Then
            oGlobalLib.createLibrary( DestLibraryName )
          End If
          If oLib.hasByName( SrcLibraryName ) Then
            oLib.loadLibrary( SrcLibraryName )
            oSrcLib = oLib.getByName( SrcLibraryName )
            sSrcModules = oSrcLib.getElementNames()
            iCounter = lBound( sSrcModules() )
       
            while( iCounter &lt;= uBound( sSrcModules() ) )
              oDestLib = oGlobalLib.getByName(DestLibraryName)
              If oDestLib.hasByName( sSrcModules(iCounter) ) = False Then
                oDestLib.insertByName( sSrcModules(iCounter),_
                oSrcLib.getByName( sSrcModules(iCounter) ) )
              End If
              iCounter = iCounter + 1
            wend
          End If
       
          oLib = DialogLibraries   ' The same for the Dialog libraries
          oGlobalLib = GlobalScope.DialogLibraries
        Next iLib
       End Sub
    7. Replace the SrcLibraryName and DestLibraryName variables with the name of your library.
    8. Close the BASIC IDE window.
  4. Add a push button to the document.
    1. On the Form Controls toolbar, click the Push Button icon.
    2. In your document, drag to draw the button.
  5. Assign the installation macro to a button event.
    1. Right-click the new button and choose Control.
    2. Click the Events tab.
    3. Click the ellipsis (...) next to a button event. For example, the Mouse button pressed event might be used.
    4. In the Assign Action dialog box, click the Macro button. The Macro Selector dialog box appears.
    5. In the Library list, select the library that contains the installation macro.
    6. In the Macro name list, select the installation macro.
    7. Click OK.
    8. In the Assign Macro dialog box, click OK.
  6. Save the document.
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages