Implementation

OpenOffice.org Developer's Guide

Scripting Framework

< Previous Section

Next Section >

• Using the Scripting Framework

• Running Macros
• Editing, Creating and Managing Macros

• The Organizer dialogs for BeanShell and JavaScript
• BeanShell Editor
• JavaScript Editor
• Basic and Dialogs
• Macro Recording

• Writing Macros
• How the Scripting Framework Works
• Writing a LanguageScriptProvider UNO Component using the Java Helper Classes

• The ScriptProvider Abstract Base Class
• Implementing the XScript Interface
• Implementing the ScriptEditor Interface
• Building and Registering Your ScriptProvider

• Writing a LanguageScriptProvider UNO Component From Scratch

• Scripting Framework URI Specification
• Storage of Scripts
• Implementation
• Integration with Extension Manager

< Previous Page

Next Page >

A LanguageScriptProvider implementation must follow the service definition com.sun.star.script.provider.LanguageScriptProvider

Since a LanguageScriptProvider is an UNO component, it must additionally contain the component operations needed by a UNO service manager. These operations are certain static methods in Java or export functions in C++. It also has to implement the core interfaces used to enable communication with UNO and the application environment. For more information on the component operations and core interfaces, please see Component Architecture and Core Interfaces to Implement.

LanguageScriptProvider

The interface Initialization supports method:

 void initialize( [in] sequence<any> arguments )

The LanguageScriptProvider is responsible for organizing and execution of macros written in a specific language for a certain location. The possible locations for macros are within a document or either the user or share directories in an Apache OpenOffice installation. The LanguageScriptProvider is initialized for given location context which is passed as the first argument to the initialize() method. The location context is a string with the following possible values

Location context
"user"	String. Denotes the user directory in a Apache OpenOffice installation
"share"	String. Denotes the share directory in a Apache OpenOffice installation
url	String. For user or share directory, the URL has scheme vnd.sun.star.expand example: user directory "vnd.sun.star.expand:${$SYSBINDIR/bootstraprc/::UserInstallation}/user" share directory "vnd.sun.star.expand:${$SYSBINDIR/bootstraprc/::BaseInstallation}/share"
	Where for a currently open document, the URL has scheme vnd.sun.star.tdoc example: vnd.sun.star.tdoc:/1

The com.sun.star.script.browse.XBrowseNode interface supported by a LanguageScriptProvider service is the initial point of contact for the Apache OpenOffice application. In order for the %PRODUCNAME to process and display macros, it needs to be able to list those macros. Additionally, the MacroOrganizer dialogs use the com.sun.star.script.browse.BrowseNode service to create/delete new macros and macro libraries.

The interface com.sun.star.script.browse.XBrowseNode supports the following methods:

  string getName()
  sequence < ::com::sun::star::script::browse::XBrowseNode > getChildNodes()
  boolean hasChildNodes()
  short getType()

The method getName() returns the name of the node.

For the root node of a LanguageScriptProvider, the name returned from getName() is expected to be the language name as it would appear in a script URI e.g. Basic

The method getChildNodes() method should return the nodes which represent the next level in the hierarchy of macros and macro Libraries the LanguageScriptProvider is managing.

The method getType() returns the type of the node.

Nodes can be of three types represented by the constants com.sun.star.script.browse.BrowseNodeTypes

Constants of com.sun.star.script.browse.BrowseNodeTypes
Value	Description
SCRIPT	Indicates that the node is a script.
CONTAINER	Indicates that the node is a container of other nodes e.g. Library
ROOT	Reserved for use by the ScriptingFramework.

The objects implementing XBrowseNodes can must also implement com.sun.star.beans.XPropertySet.

Properties of object implementing com.sun.star.script.browse.BrowseNode
Uri	string. Found on script nodes only, is the script URI for the macro associated with this node.
Description	string. Found on script nodes only, is a description of the macro associated with this node.
Creatable	boolean. True if the implementation can create a new container or macro as a child of this node.
Creatable	boolean. True if the implementation can delete this node.
Editable	boolean. True if the implementation is able to open the macro in an editor.
Renamable	boolean. True if the implementation can rename this node.

Note that a node that has the Creatable, Deletable, Editable or Renamable properties set to true is expected to implement the com.sun.star.script.XInvocation interface.

The interface com.sun.star.script.XInvocation supports the following methods:

  com::sun::star::beans::XIntrospectionAccess getIntrospection(); 
  any invoke( [in] string aFunctionName, 
              [in] sequence<any> aParams, 
              [out] sequence<short> aOutParamIndex, 
              [out] sequence<any> aOutParam )
 
  void setValue( [in] string aPropertyName, 
                 [in] any aValue ) 
 
  any getValue( [in] string aPropertyName ) 
 
  boolean hasMethod( [in] string aName )
 
  boolean hasProperty( [in] string aName )

The invoke() function is passed as an argument the property keys of the com.sun.star.script.browse.BrowseNode service

Elements of aParam sequence in invoke call
aFunctionName	aParams
Editable	None required.
Creatable	aParam[0] should contain the name of the new child node to be created.
Deletable	None required.
Renamable	aParam[0] should contain the new name for the node.
Uri	None required.
Description	None required.

Access to a macro if provided for by the com.sun.star.script.provider.XScriptProviderinterface which supports the following method:

  ::com::sun::star::script::provider::XScript getScript( [in] string sScriptURI )

The getScript() method is passed a script URI sScriptURI and the LanguageScriptProvider implementation needs to parse this URI so it can interpret the details and validate them. As the LanguageScriptProvider is responsible for exporting and generating the URI associated with a macro, it is also responsible for performing the reverse translation for a give n URI and returning an object implementing com.sun.star.script.provider.XScript interface which will allow the macro to be invoked.

com.sun.star.script.provider.XScript which supports the following methods:

  any invoke( [in] sequence<any> aParams, 
              [out] sequence<short> aOutParamIndex, 
              [out] sequence<any> aOutParam )

In addition to the parameters that may be passed to an object implementing com.sun.star.script.provider.XScript it is up to that object to decide what extra information to pass to a running macro. It makes sense to pass information to the macro, which makes the macro writer's job easier. Information such as a reference to the document (context), a reference to the service manager (available from the component context passed into the LanguageScriptProvider component's constructor by UNO), and a reference to the desktop (available from UNO using this service manager).

All the Java based reference LanguagesScriptProvider provided with Apache OpenOffice make this information available to the running macro in the form of an object implementing the interface com.sun.star.script.provider.XScriptContext. This provides accessor methods to get the current document, the desktop and the component context. Depending on the constraints of the language this information is passed to the macros in different ways, for example in Beanshell and JavaScript this is available as an environment variable and in the case of Java it is passed as the first argument to the macro.

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