General Developer Guidelines

Writing Office scripts and the XScriptContext type

• Current document - access the document context against which the script was invoked

  <XScriptContext Instance>.getDocument()
  returns ::com::sun::star::frame::XModel

• Office Desktop - access the desktop of the running Office

  <XScriptContext Instance>.getDesktop()
  returns ::com::sun::star::frame::XDesktop

• Component Factory - access a ComponentContext factory to create other UNO components as required

  <XScriptContext Instance>.getComponentContext()
  returns ::com::sun::star::uno::XComponentContext

    import drafts.com.sun.star.script.framework.XScriptContext;

    import com.sun.star.frame.XModel;
    import com.sun.star.text.*;
    import com.sun.star.uno.UnoRuntime;
    import drafts.com.sun.star.script.framework.XScriptContext;

    public class MyClass {

        // The script method must be public
        // It can either be static or non-static

        public void showForm(XScriptContext xSc) {

            // getting the text document object
            XModel xmodel = xSc.getDocument();

            XTextDocument xtextdoc = (XTextDocument)
                UnoRuntime.queryInterface(XTextDocument.class, xmodel);
            XText xtext = xtextdoc.getText();
            XTextCursor xtextcursor = xtext.createTextCursor();

            xtext.insertString(xtextcursor, "Hello World", false);
        }
    }

Tips on writing Office scripts

• Performance: Currently scripts are being loaded by the Scripting Framework each time they are run. As such it is important to keep the size of your scripts and any dependent jar files they are using reasonably small. In future releases this script loading will be optimised by changing the point at which the scripts are loaded by OpenOffice.org and using various caching schemes once they are loaded. However, the initial load will always be effected by the script and it's dependent jar/class file sizes.

• Threading: Scripts are run synchronously by the Scripting Framework. If you wish to perform any background task or provide some user interaction via a dialog for instance, then it is your responsibility to spawn a thread in the running script which can manage this process or interaction and let the script return promptly. Within this running thread you should follow the normal UNO component threading guidelines to ensure that they do not deadlock OpenOffice.org through inappropriate use of the UNO API.

Parcel Descriptor DTD and sample XML

<?xml version="1.0" encoding="UTF-8"?>
<!-- DTD for Parcel Meta data for use in the OpenOffice.org Scripting Framework Project -->
<!ELEMENT logicalname EMPTY>
<!ELEMENT description (#PCDATA)>
<!ELEMENT displayname EMPTY>
<!ELEMENT locale (displayname?, description?)>
<!ELEMENT functionname EMPTY>
<!ELEMENT prop EMPTY>
<!ELEMENT languagedepprops (prop+)>
<!ELEMENT file (prop*)>
<!ELEMENT fileset (file+)>
<!ELEMENT script (locale+, functionname, logicalname, languagedepprops*, fileset*)>
<!ELEMENT parcel (script+)>
<!ATTLIST logicalname
	value CDATA #REQUIRED
>
<!ATTLIST displayname
	value CDATA #REQUIRED
>
<!ATTLIST locale
	lang CDATA #REQUIRED
>
<!ATTLIST functionname
	value CDATA #REQUIRED
>
<!ATTLIST logicalname
	value CDATA #REQUIRED
>
<!ATTLIST prop
	name CDATA #REQUIRED
	value CDATA #REQUIRED
>
<!ATTLIST file
	name CDATA #REQUIRED
>
<!ATTLIST fileset
	name CDATA #IMPLIED
>
<!ATTLIST script
	language CDATA #REQUIRED
>

<?xml version="1.0" encoding="UTF-8"?>
<!--Sample Meta Data for use with the Scripting Framework Project in OpenOffice.org -->
<!DOCTYPE parcel SYSTEM "parcel.dtd">
<parcel>
	<script language="java">
		<locale lang="english">
			<displayname value="Memory.usage"/>
			<description>
				Displays the memory current memory usage
			</description>
		</locale>
		<functionname value="memoryUtils.memoryUsage"/>
		<logicalname value="MemoryUtils.MemUsage"/>
		<languagedepprops>
			<prop name="classpath" value="/opt/foo.jar:/usr/java/src.jar"/>
		</languagedepprops>
		<fileset>
			<file name="mems.txt">
				<prop name="type" value="resource"/>
			</file>
		</fileset>
	</script>
</parcel>

How to Bind Scripts

• Start OpenOffice.org and open an existing document or create a new one.
• Select the menu item Tools/Assign Scripts (Java) To/Menu...
• In the "Assign Scripts (Java) To Menu" dialog that pops up do the following:
  • Select script function
    • Select the script function that you require from the list.
  • Choose the menu to insert the script menu after
    • Select the top level menu and submenu under which you want to place your new menu item.
  • Assign script to new menu
    • In the New Menu text field enter the label you want for your menu item
    • Click New Script Menu to create the new script menu item.
• Finally click on the OK button to save your new script menu item.
• Restart OpenOffice.org and open a document
• Your new menu item will now be available and clicking on it will invoke the Java script.

• Start OpenOffice.org and open an existing document or create a new one.
• Select the menu item Tools/Assign Scripts (Java) To/Key...
• In the "Assign Scripts (Java) To Key" dialog that pops up do the following:
  • Select script function
    • Select the script function that you require from the list.
  • Choose the Shortcut key to bind the script to
    • Select one of the Key Groups (e.g. SHIFT + CONTROL + digits)
    • Select a key from the Shortcut Keys.
  • Assign script to shortcut key: Click New Script Key to create the new script Shortcut key.