Overview and Using the API

From Apache OpenOffice Wiki
Jump to: navigation, search


The com.sun.star.i18n.XLocaleData interface provides access to locale-specific information, such as decimal separators, group (thousands) separators, currency information, calendar data, and number format codes. No further functionality is discussed.


The com.sun.star.i18n.XCharacterClassification interface is used to determine the Unicode type of a character (such as uppercase, lowercase, letter, digit, punctuation) or the script type. It also provides methods to perform simple uppercase to lowercase and lowercase to upper case conversions that are locale-dependent but do not need real transliteration. An example of locale-dependent case conversion is the Turkish lowercase i to uppercase I-dot and lowercase i-dotless to uppercase I conversion, as opposed to the western lowercase i to uppercase I conversion.

Documentation caution.png There was a bug in OpenOffice.org 1.0.2 that prevents this special example of Turkish case conversion to work properly. The issue is resolved for OpenOffice.org 1.1.0.

Another provided functionality is parsing methods to isolate and determine identifiers, numbers, and quoted strings in a given string. See the description of com.sun.star.i18n.XCharacterClassification methods parseAnyToken() and parsePredefinedToken(). The parser uses com.sun.star.i18n.XLocaleData to obtain the locale-dependent decimal and group separators.


The com.sun.star.i18n.XCalendar interface enables the application to use any calendar available for a given locale, not being restricted to the Gregorian calendar. You may query the interface for the available calendars for a given locale with method getAllCalendars() and load one of the available calendars using method loadCalendar(), or you may use the default calendar loaded with method loadDefaultCalendar(). Normally, a Gregorian calendar is available with the name "gregorian" in the Name field of com.sun.star.i18n.Calendar even if the default calendar is not a Gregorian calendar, but this is not mandatory. Available calendars are obtained through the com.sun.star.i18n.XLocaleData interface.

Documentation caution.png You must initially load a calendar before using any of the interface methods that perform calendar calculations.


The com.sun.star.i18n.XExtendedCalendar interface was introduced with OpenOffice.org 1.1.0 and provides additional functionality to display locale and calendar dependent calendar values. This interface is derived from com.sun.star.i18n.XCalendar. The interface provides a method to obtain display strings of date parts for specific calendars of a specific locale.


The com.sun.star.i18n.XNumberFormatCode interface provides access to predefined number format codes for a given locale, which in turn are obtained through the com.sun.star.i18n.XLocaleData interface. Normally you do not need to bother with it because the application's number formatter Number Formats manages the codes. It just might serve to get the available codes and determine default format codes of a specific category.


The com.sun.star.i18n.XNativeNumberSupplier interface was introduced with OpenOffice.org 1.1.0 and provides functionality to convert between ASCII Arabic digits/numeric strings and native numeral strings, such as Korean number symbols.


The com.sun.star.i18n.XCollator interface provides locale-dependent collation algorithms for sorting purposes. There is at least one collator algorithm available per locale, though there may be more than one, for example dictionary and telephone algorithms, or stroke, radical, pinyin in Chinese locales. There is always one default algorithm for each locale that may be loaded using method loadDefaultCollator(), and all available algorithms may be queried with method listCollatorAlgorithms() of those a selected algorithm may be loaded using loadCollatorAlgorithm(). The available collator implementations and options are obtained through the com.sun.star.i18n.XLocaleData interface.

Documentation caution.png You must initially load an algorithm prior to using any of the compare...() methods, otherwise the result will be 0 indicating any comparison being equal.

Documentation note.png Since collation may be a very time consuming procedure, use it only for user-visible data, for example for sorted lists. If, for example, you only need a case insensitive comparison without displaying the results to the user, use the com.sun.star.i18n.XTransliteration interface instead.


The com.sun.star.i18n.XTransliteration interface provides methods to perform locale-dependent character conversions, such as case conversions, conversions between Hiragana and Katakana, and Half-width and Full-width. Transliteration is also used by the collators if, for example, a case insensitive sort is to be performed. The available transliteration implementations are obtained through the com.sun.star.i18n.XLocaleData interface.

Documentation caution.png You must initially load a transliteration module prior to using any of the transliterating or comparing methods, otherwise the result is unpredictable.

Documentation note.png If you only need to determine if two strings are equal for a specific transliteration (for example a case insensitive comparison) use the equals() method instead of the compare...() methods, it may have a faster implementation.


The com.sun.star.i18n.XTextConversion interface provides methods to perform locale-dependent text conversions, such as Hangul/Hanja conversion for Korean, or translation between Chinese simplified and Chinese traditional.


The com.sun.star.i18n.XBreakIterator interface may be used to traverse the text in character mode or word mode, to jump to the beginning or to the end of a sentence, to find the beginning or the end of a given script type, and, as the name suggests, to determine a line break position, optionally using a com.sun.star.linguistic2.XHyphenator. The service implementation obtains lists of forbidden characters (characters that are not allowed at the beginning or the end of a line in certain locales) through the com.sun.star.i18n.XLocaleData interface. The XBreakIterator interface also offers methods to determine the script type of a character or to find the beginning or end of a script type along a sequence of characters.


The com.sun.star.i18n.XIndexEntrySupplier interface may be used to obtain information on index entries to generate a "table of alphabetical index" for a given locale. Since not all languages are alphabetical in the western sense (for example, CJK languages), different methods are needed.


The com.sun.star.i18n.XExtendedIndexEntrySupplier interface was introduced with OpenOffice.org 1.1.0 and provides additional functionality to generate index entries for languages that need phonetically sorted indexes, such as Japanese. The interface is derived from com.sun.star.i18n.XIndexEntrySupplier.

XInputSequenceCheckerThe com.sun.star.i18n.XInputSequenceChecker interface was introduced with OpenOffice.org 1.1.0 and provides input sequence checking for Thai and Hindi.

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