Linguistics

From Apache OpenOffice Wiki
Jump to: navigation, search



The Linguistic API provides a set of UNO services used for spell checking, hyphenation or accessing a thesaurus. Through the Linguistic API, developers add new implementations and integrate them into Apache OpenOffice. Users of the Linguistic API call its methods Usually this functionality is used by one or more clients, that is, applications or components, to process documents such as text documents or spreadsheets.

Services Overview

The services provided by the Linguistic API are:

Also there is at least one or more implementation for each of the following services:

The service implementations for spell checker, thesaurus and hyphenator supply the respective functionality. Each of the implementations support a different set of languages. Refer to com.sun.star.linguistic2.XSupportedLocales.

For example, there could be two implementations for a spell checker, usually from different supporting parties: the first supporting English, French and German, and the second supporting Russian and English. Similar settings occur for the hyphenator and thesaurus.

It is not convenient for each application or component to know all these implementations and to choose the appropriate implementation for the specific purpose and language, therefore a mediating instance is required.

This instance is the LinguServiceManager. Spell checking, hyphenation and thesaurus functionality is accessed from a client by using the respective interfaces from the LinguServiceManager.

The LinguServiceManager dispatches the interface calls from the client to a specific service implementation, if any, of the respective type that supports the required language. For example, if the client requires spell checking of a French word, the first spell checker implementations from those mentioned above are called.

If there is more than one spell checker available for one language, as in the above example for the English language, the LinguServiceManager starts with the first one that was supplied in the setConfiguredServices() method of its interface. The thesaurus behaves similarly. For more details, refer to the interface description com.sun.star.linguistic2.XLinguServiceManager.

The LinguProperties service provides, among others, properties that are required by the spell checker, hyphenator and thesaurus that are modified by the client. Refer to the com.sun.star.linguistic2.LinguProperties.

The DictionaryList (see com.sun.star.linguistic2.DictionaryList) provides a set of user defined or predefined dictionaries for languages that are activated and deactivated. If they are active, they are used by the spell checker and hyphenator. These are used by the user to override results from the spell checker and hyphenator implementations, thus allowing the user to customize spell checking and hyphenation.

In the code snippets and examples in the following chapters, we will use the following members and interfaces:

  // used interfaces
  import com.sun.star.lang.XMultiServiceFactory;
  import com.sun.star.linguistic2.XLinguServiceManager;
  import com.sun.star.linguistic2.XSpellChecker;
  import com.sun.star.linguistic2.XHyphenator;
  import com.sun.star.linguistic2.XThesaurus;
  import com.sun.star.linguistic2.XSpellAlternatives;
  import com.sun.star.linguistic2.XHyphenatedWord;
  import com.sun.star.linguistic2.XPossibleHyphens;
  import com.sun.star.linguistic2.XMeaning;
  import com.sun.star.linguistic2.XSearchableDictionaryList;
  import com.sun.star.linguistic2.XLinguServiceEventListener;
  import com.sun.star.linguistic2.LinguServiceEvent;
  import com.sun.star.beans.XPropertySet;
  import com.sun.star.beans.PropertyValue;
  import com.sun.star.uno.XComponentContext;
  import com.sun.star.uno.XNamingService;
  import com.sun.star.lang.XMultiComponentFactory;
  import com.sun.star.lang.EventObject;
  import com.sun.star.lang.Locale;
  import com.sun.star.bridge.XUnoUrlResolver;
  import com.sun.star.uno.UnoRuntime;
  import com.sun.star.uno.Any;
  import com.sun.star.lang.XComponent;
 
  //
  // members for commonly used interfaces
  //
 
  // The MultiServiceFactory interface of the Office
  protected XMultiServiceFactory mxFactory = null;
 
  // The LinguServiceManager interface
  protected XLinguServiceManager mxLinguSvcMgr = null;
 
  // The SpellChecker interface
  protected XSpellChecker mxSpell = null;
 
  // The Hyphenator interface
  protected XHyphenator mxHyph = null;
 
  // The Thesaurus interface
  protected XThesaurus mxThes = null;
 
  // The DictionaryList interface
  protected XSearchableDictionaryList mxDicList = null;
 
  // The LinguProperties interface
  protected XPropertySet mxLinguProps = null;

To establish a connection to the office and have our mxFactory object initialized with its XMultiServiceFactory, the following code is used:

  public void Connect( String sConnection )
      throws com.sun.star.uno.Exception,
      com.sun.star.uno.RuntimeException, 
      Exception
  {
      XComponentContext xContext = 
          com.sun.star.comp.helper.Bootstrap.createInitialComponentContext( null 
  );
      XMultiComponentFactory xLocalServiceManager = xContext.getServiceManager();
 
      Object xUrlResolver = xLocalServiceManager.createInstanceWithContext( 
          "com.sun.star.bridge.UnoUrlResolver", xContext );
      XUnoUrlResolver urlResolver = (XUnoUrlResolver)UnoRuntime.queryInterface( 
          XUnoUrlResolver.class, xUrlResolver );
      Object rInitialObject = urlResolver.resolve( "uno:" + sConnection +
          ";urp;StarOffice.NamingService" );
      XNamingService rName = (XNamingService)UnoRuntime.queryInterface(XNamingService.class,
          rInitialObject );
      if( rName != null ) 
      {
          Object rXsmgr = rName.getRegisteredObject( "StarOffice.ServiceManager" );
          mxFactory = (XMultiServiceFactory)
              UnoRuntime.queryInterface( XMultiServiceFactory.class, rXsmgr );
      }
  }

And the LinguServiceManager object mxLinguSvcMgr is initialized like in the following snippet:

  /** Get the LinguServiceManager to be used. For example to access spell checker, 
      thesaurus and hyphenator, also the component may choose to register itself
      as listener to it in order to get notified of relevant events. */
  public boolean GetLinguSvcMgr()
      throws com.sun.star.uno.Exception
  {
      if (mxFactory != null) {
          Object aObj = mxFactory.createInstance(
              "com.sun.star.linguistic2.LinguServiceManager" );
          mxLinguSvcMgr = (XLinguServiceManager) 
              UnoRuntime.queryInterface(XLinguServiceManager.class, aObj);
      }
      return mxLinguSvcMgr != null;
  }

The empty list of temporary property values used for the current function call only and the language used may look like the following:

  // list of property values to used in function calls below.
  // Only properties with values different from the (default) values
  // in the LinguProperties property set need to be supplied.
  // Thus we may stay with an empty list in order to use the ones
  // form the property set.
  PropertyValue[] aEmptyProps = new PropertyValue[0];
 
  // use american english as language
  Locale aLocale = new Locale("en","US","");

Using temporary property values:

To change a value for the example IsGermanPreReform to a different value for one or a limited number of calls without modifying the default values, provide this value as a member of the last function argument used in the examples below before calling the respective functions.

  // another list of property values to used in function calls below.
  // Only properties with values different from the (default) values
  // in the LinguProperties property set need to be supplied.
  PropertyValue[] aProps = new PropertyValue[1];
  aProps[0] = new PropertyValue();
  aProps[0].Name = "IsGermanPreReform";
  aProps[0].Value = new Boolean( true );

Replace the aEmptyProps argument in the function calls with aProps to override the value of IsGermanPreReform from the LinguProperties. Other properties are overridden by adding them to the aProps object.

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