Path Settings

From Apache OpenOffice Wiki
Jump to: navigation, search



The com.sun.star.util.PathSettings service supports a number of properties which store the OpenOffice.org predefined paths. There are two different groups of properties. One group stores only a single path and the other group stores two or more paths - separated by a semicolon.

Properties of com.sun.star.util.PathSettings
Addin Single path Specifies the directory that contains spreadsheet add-ins which use the old add-in API.
AutoCorrect Multi path Specifies the directories that contain the settings for the AutoCorrect dialog.
AutoText Multi path Specifies the directories that contain the AutoText modules.
Backup Single path Specifies the directory for storing automatic backup copies of documents.
Basic Multi path Specifies the location of the Basic files that are used by the AutoPilots.
Bitmap Single path Specifies the directory that contains the external icons for the toolbars.
Config Single path Specifies the location of the configuration files. This property is not visible in the OpenOffice.org path options dialog and cannot be changed by users.
Dictionary Single path Specifies the location of the OpenOffice.org dictionaries.
Favorite Single path Specifies the directory that contains the saved folder bookmarks.
Filter Single path Specifies the directory where the filters are stored.
Gallery Multi path Specifies the directories that contain the Gallery database and multimedia files.
Graphic Single path Specifies the directory that is displayed when the dialog for opening a graphic or for saving a new graphic is called.
Help Single path Specifies the location of the Office help files.
Linguistic Single path Specifies the directory where the spellcheck files are stored.
Module Single path Specifies the directory where the modules are stored.
Palette Single path Specifies the location of the palette files that contain user-defined colors and patterns (*.SOB and *.SOF).
Plugin Multi path Specifies the directories where the Plugins are stored.
Storage Single path Specifies the directory where mail and news files as well as other information (for example, about FTP Server) are stored. This property is not visible in the OpenOffice.org path options dialog and cannot be changed by users.
Temp Single path Specifies the directory for the office temp-files.
Template Multi path Specifies the directory for the OpenOffice.org document templates.
UIConfig Multi path Specifies the location of global directories when looking for user interface configuration files. The user interface configuration is merged with the user settings that are stored in the directory specified by UserConfig.
UserConfig Single path Specifies the directory that contains the user settings, including the user interface configuration files for menus, toolbars, accelerators and status bars.
UserDictionary Single path Specifies the directory for the custom dictionaries.
Work Single path Specifies the location of the work folder. This path can be modified according to the user's needs and can be seen in the Open or Save dialog.

Configuration

The path settings service uses the group Path in the org.Openoffice.Office.Common branch to read and store paths. The Current and Default groups in the share layer of the configuration branch store the path settings properties. The Current group initialize the properties of the path settings service during startup. If the user activates the Default button in the path options dialog, the Default group values are copied to the current ones.

Documentation note.png Note: The configuration branch separates the paths of a property with a colon (:), whereas the path settings service separates multiple paths with a semicolon (;).
  <?xml version='1.0' encoding='UTF-8'?>
  <oor:component-schema oor:name="Common" oor:package="org.openoffice.Office" xml:lang="en-US" xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://wwww.w3.org/2001/XMLSchema-instance">
      <component>
          <group oor:name="Path">
              <group oor:name="Current">
                  <prop oor:name="OfficeInstall" oor:type="xs:string">
                      <value/>
                  </prop>
                  <prop oor:name="OfficeInstallURL" oor:type="xs:string">
                      <value/>
                  </prop>
                  <prop oor:name="Addin" oor:type="xs:string">
                      <value>$(progpath)/addin</value>
                  </prop>
                  <prop oor:name="AutoCorrect" oor:type="oor:string-list">
                      <value oor:separator=":">$(insturl)/share/autocorr:$(userurl)/autocorr</value>
                  </prop>
                  <prop oor:name="AutoText" oor:type="oor:string-list">
                      <value oor:separator=":">
                          $(insturl)/share/autotext/$(vlang):$(userurl)/autotext
                      </value>
                  </prop>
                  <prop oor:name="Backup" oor:type="xs:string">
                      <value>$(userurl)/backup</value>
                  </prop>
                  <prop oor:name="Basic" oor:type="oor:string-list">
                      <value oor:separator=":">$(insturl)/share/basic:$(userurl)/basic</value>
                  </prop>
                  <prop oor:name="Bitmap" oor:type="xs:string">
                      <value>$(insturl)/share/config/symbol</value>
                  </prop>
                  <prop oor:name="Config" oor:type="xs:string">
                      <value>$(insturl)/share/config</value>
                  </prop>
                  <prop oor:name="Dictionary" oor:type="xs:string">
                      <value>$(insturl)/share/wordbook/$(vlang)</value>
                  </prop>
                  <prop oor:name="Favorite" oor:type="xs:string">
                      <value>$(userurl)/config/folders</value>
                  </prop>
                  <prop oor:name="Filter" oor:type="xs:string">
                      <value>$(progpath)/filter</value>
                  </prop>
                  <prop oor:name="Gallery" oor:type="oor:string-list">
                    <value oor:separator=":">$(insturl)/share/gallery:$(userurl)/gallery</value>
                  </prop>
                  <prop oor:name="Graphic" oor:type="xs:string">
                      <value>$(insturl)/share/gallery</value>
                  </prop>
                  <prop oor:name="Help" oor:type="xs:string">
                      <value>$(instpath)/help</value>
                  </prop>
                  <prop oor:name="Linguistic" oor:type="xs:string">
                      <value>$(insturl)/share/dict</value>
                  </prop>
                  <prop oor:name="Module" oor:type="xs:string">
                      <value>$(progpath)</value>
                  </prop>
                  <prop oor:name="Palette" oor:type="xs:string">
                      <value>$(userurl)/config</value>
                  </prop>
                  <prop oor:name="Plugin" oor:type="oor:string-list">
                      <value oor:separator=":">$(userpath)/plugin</value>
                  </prop>
                  <prop oor:name="Storage" oor:type="xs:string">
                      <value>$(userpath)/store</value>
                  </prop>
                  <prop oor:name="Temp" oor:type="xs:string">
                      <value>$(temp)</value>
                  </prop>
                  <prop oor:name="Template" oor:type="oor:string-list">
                      <value oor:separator=":">
                          $(insturl)/share/template/$(vlang):$(userurl)/template
                      </value>
                  </prop>
                  <prop oor:name="UIConfig" oor:type="oor:string-list">
                      <value oor:separator=":"/>
                  </prop>
                  <prop oor:name="UserConfig" oor:type="xs:string">
                      <value>$(userurl)/config</value>
                  </prop>
                  <prop oor:name="UserDictionary" oor:type="xs:string">
                      <value>$(userurl)/wordbook</value>
                  </prop>
                  <prop oor:name="Work" oor:type="xs:string">
                      <value>$(work)</value>
                  </prop>
              </group>
              <group oor:name="Default">
                  <prop oor:name="Addin" oor:type="xs:string">
                      <value>$(progpath)/addin</value>
                  </prop>
                  <prop oor:name="AutoCorrect" oor:type="oor:string-list">
                      <value oor:separator=":">
                          $(insturl)/share/autocorr:$(userurl)/autocorr
                      </value>
                  </prop>
                  <prop oor:name="AutoText" oor:type="oor:string-list">
                      <value oor:separator=":">
                          $(insturl)/share/autotext/$(vlang):$(userurl)/autotext
                      </value>
                  </prop>
                  <prop oor:name="Backup" oor:type="xs:string">
                      <value>$(userurl)/backup</value>
                  </prop>
                  <prop oor:name="Basic" oor:type="oor:string-list">
                      <value oor:separator=":">$(insturl)/share/basic:$(userurl)/basic</value>
                  </prop>
                  <prop oor:name="Bitmap" oor:type="xs:string">
                      <value>$(insturl)/share/config/symbol</value>
                  </prop>
                  <prop oor:name="Config" oor:type="xs:string">
                      <value>$(insturl)/share/config</value>
                  </prop>
                  <prop oor:name="Dictionary" oor:type="xs:string">
                      <value>$(insturl)/share/wordbook/$(vlang)</value>
                  </prop>
                  <prop oor:name="Favorite" oor:type="xs:string">
                      <value>$(userurl)/config/folders</value>
                  </prop>
                  <prop oor:name="Filter" oor:type="xs:string">
                      <value>$(progpath)/filter</value>
                  </prop>
                  <prop oor:name="Gallery" oor:type="oor:string-list">
                      <value oor:separator=":">$(insturl)/share/gallery:$(userurl)/gallery</value>
                  </prop>
                  <prop oor:name="Graphic" oor:type="xs:string">
                     <value>$(insturl)/share/gallery</value>
                  </prop>
                  <prop oor:name="Help" oor:type="xs:string">
                     <value>$(instpath)/help</value>
                  </prop>
                  <prop oor:name="Linguistic" oor:type="xs:string">
                      <value>$(insturl)/share/dict</value>
                  </prop>
                  <prop oor:name="Module" oor:type="xs:string">
                      <value>$(progpath)</value>
                  </prop>
                  <prop oor:name="Palette" oor:type="xs:string">
                      <value>$(userurl)/config</value>
                  </prop>
                  <prop oor:name="Plugin" oor:type="oor:string-list">
                      <value oor:separator=":">$(userpath)/plugin</value>
                  </prop>
                  <prop oor:name="Temp" oor:type="xs:string">
                      <value>$(temp)</value>
                  </prop>
                  <prop oor:name="Template" oor:type="oor:string-list">
                      <value oor:separator=":">
                          $(insturl)/share/template/$(vlang):$(userurl)/template
                      </value>
                  </prop>
                  <prop oor:name="UIConfig" oor:type="oor:string-list">
                      <value oor:separator=":"/>
                  </prop>
                  <prop oor:name="UserConfig" oor:type="xs:string">
                      <value>$(userurl)/config</value>
                  </prop>
                  <prop oor:name="UserDictionary" oor:type="xs:string">
                      <value>$(userurl)/wordbook</value>
                  </prop>
                  <prop oor:name="Work" oor:type="xs:string">
                      <value>$(work)</value>
                  </prop>
              </group>
          </group>
      </component>
  </oor:component-schema>

Accessing Path Settings

The path settings service is a one-instance service that supports the com.sun.star.beans.XPropertySet, com.sun.star.beans.XFastPropertySet and com.sun.star.beans.XMultiPropertySet interfaces for access to the properties.

The service can be created using the service manager of OpenOffice.org and the service name com.sun.star.util.PathSettings. The following example creates the path settings service.

  import com.sun.star.lang.XMultiServiceFactory;
  import com.sun.star.uno.Exception;
  import com.sun.star.uno.XInterface;
  import com.sun.star.beans.XPropertySet
 
  XPropertySet createPathSettings() {
 
      // Obtain Process Service Manager.
      XMultiServiceFactory xServiceFactory = ...
 
      // Create Path settings service. Needs to be done only once per process.
      XInterface xPathSettings;
      try {
          xPathSettings = xServiceFactory.createInstance("com.sun.star.util.PathSettings" );
      }
      catch (com.sun.star.uno.Exception e) {
      }
 
      if (xPathSettings != null)
          return (XpropertySet) UnoRuntime.queryInterface(XPropertySet.class, xPathSettings);
      else
          return null;
  }

The main interface of the path settings service is com.sun.star.beans.XPropertySet. You can retrieve and write properties with this interface. It also supports getting information about the properties themselves.

  • com::sun::star::beans::XPropertySetInfo getPropertySetInfo();
The path settings service returns an XPropertySetInfo interface where more information about the path properties can be retrieved. The information includes the name of the property, a handle for faster access with XFastPropertySet, the type of the property value and attribute values.
  • void setPropertyValue( [in] string aPropertyName, [in] any aValue );
This function can set the path properties to a new value. The path settings service expects that a value of type string is provided. The string must be a correctly encoded file URL. If the path property supports multiple paths, each path must be separated by a semicolon (;). Path variables are also allowed, so long as they can be resolved to a valid file URL.
  • any getPropertyValue( [in] string PropertyName );
This function retrieves the value of a path property. The property name must be provided and the path is returned. The path settings service always returns the path as a file URL. If the property value includes multiple paths, each path is separated by a semicolon (;).
Documentation note.png Note: The path settings service always provides property values as file URLs. Properties which are marked as multi path (see table above) use a semicolon (;) as a separator for the different paths. The service also expects that a new value for a path property is provided as a file URL or has a preceding path variable, otherwise a com.sun.star.lang.IllegalArgumentException is thrown.

The illustration below shows how the path settings, path substitution, and configuration service work together to read or write path properties.

Interaction of path settings, path substitution and configuration
Documentation caution.png Important: Keep in mind that the paths managed by the path settings service are vital for almost all of the functions in OpenOffice.org. Entering a wrong path can result in minor malfunctions or break the complete OpenOffice.org installation. Although the path settings service performs a validity check on the provided URL, this cannot prevent all problems.


The following code example uses the path settings service to retrieve and set the path properties.

  import com.sun.star.bridge.XUnoUrlResolver;
  import com.sun.star.uno.UnoRuntime;
  import com.sun.star.uno.XComponentContext;
  import com.sun.star.lang.XMultiComponentFactory;
  import com.sun.star.beans.XPropertySet;
  import com.sun.star.beans.PropertyValue;
  import com.sun.star.beans.UnknownPropertyException;
  /* Provides example code how to access and use the
   * path pathsettings servce.
   */
  public class PathSettingsTest extends java.lang.Object {
 
      /*
       * List of predefined path variables supported by
       * the path settings service.
       */
      private static String[] predefinedPathProperties = {
          "Addin",
          "AutoCorrect",
          "AutoText",
          "Backup",
          "Basic",
          "Bitmap",
          "Config",
          "Dictionary",
          "Favorite",
          "Filter",
          "Gallery",
          "Graphic",
          "Help",
          "Linguistic",
          "Module",
          "Palette",
          "Plugin",
          "Storage",
          "Temp",
          "Template",
          "UIConfig",
          "UserConfig",
          "UserDictionary",
          "Work"
      };
 
      /*
       * @param args the command line arguments
       */
      public static void main(String[] args) {
 
          XComponentContext xRemoteContext = null;
          XMultiComponentFactory xRemoteServiceManager = null;
          XPropertySet xPathSettingsService = null;
 
          try {
              // connect
              XComponentContext xLocalContext =
                  com.sun.star.comp.helper.Bootstrap.createInitialComponentContext(null);
              XMultiComponentFactory xLocalServiceManager = xLocalContext.getServiceManager();
              Object urlResolver = xLocalServiceManager.createInstanceWithContext(
                  "com.sun.star.bridge.UnoUrlResolver", xLocalContext );
              XUnoUrlResolver xUnoUrlResolver = (XUnoUrlResolver) UnoRuntime.queryInterface( 
                  XUnoUrlResolver.class, urlResolver );
              Object initialObject = xUnoUrlResolver.resolve( 
                  "uno:socket,host=localhost,port=2083;urp;StarOffice.ServiceManager" );
              XPropertySet xPropertySet = (XPropertySet)UnoRuntime.queryInterface(
                  XPropertySet.class, initialObject);
              Object context = xPropertySet.getPropertyValue("DefaultContext"); 
              xRemoteContext = (XComponentContext)UnoRuntime.queryInterface(
                  XComponentContext.class, context);
              xRemoteServiceManager = xRemoteContext.getServiceManager();
 
              Object pathSubst = xRemoteServiceManager.createInstanceWithContext(
                  "com.sun.star.comp.framework.PathSettings", xRemoteContext );
              xPathSettingsService = (XPropertySet)UnoRuntime.queryInterface(
                  XPropertySet.class, pathSubst);
 
              /* Work with path settings */
              workWithPathSettings( xPathSettingsService );
          }
          catch (java.lang.Exception e){
              e.printStackTrace();
          }
          finally {
              System.exit(0);
          }
      }
      /*
       * Retrieve and set path properties from path settings service
       * @param xPathSettingsService the path settings service
       */
      public static void workWithPathSettings(XPropertySet xPathSettingsService) {
          if (xPathSettingsService != null) {
              for (int i=0; i<predefinedPathProperties.length; i++) {
                  try {
                      /* Retrieve values for path properties from path settings service*/ 
                      Object aValue = xPathSettingsService.getPropertyValue(predefinedPathProperties[i]);
 
                      // getPropertyValue returns an Object, you have to cast it to type that you need 
                      String aPath = (String)aValue;
                      System.out.println("Property="+ predefinedPathProperties[i] + " Path=" + aPath);
                  }
                  catch (com.sun.star.beans.UnknownPropertyException e) {
                      System.out.println("UnknownPropertyException has been thrown accessing "+predefinedPathProperties[i]);
                  }
                  catch (com.sun.star.lang.WrappedTargetException e) {
                      System.out.println("WrappedTargetException has been thrown accessing "+predefinedPathProperties[i]);
                  }
              }
 
              // Try to modfiy the work path property. After running this example
              // you should see the new value of "My Documents" in the path options 
              // tab page, accessible via "Tools - Options - OpenOffice.org - Paths". 
              // If you want to revert the changes, you can also do it with the path tab page.
              try {
                  xPathSettingsService.setPropertyValue("Work", "$(temp)");
                  String aValue = (String)xPathSettingsService.getPropertyValue("Work");
                  System.out.println("The work path should now be " + aValue);
              }
              catch (com.sun.star.beans.UnknownPropertyException e) {
                  System.out.println("UnknownPropertyException has been thrown accessing PathSettings service");
              }
              catch (com.sun.star.lang.WrappedTargetException e) {
                  System.out.println("WrappedTargetException has been thrown accessing PathSettings service");
              }
              catch (com.sun.star.beans.PropertyVetoException e) {
                  System.out.println("PropertyVetoException has been thrown accessing PathSettings service");
              }
              catch (com.sun.star.lang.IllegalArgumentException e) {
                  System.out.println("IllegalArgumentException has been thrown accessing PathSettings service");
              }
          }
      }
  }


Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages