Managing Number Formats

From Apache OpenOffice Wiki
Jump to: navigation, search



Documents provide their formats through the interface com.sun.star.util.XNumberFormatsSupplier that has one method getNumberFormats() that returns com.sun.star.util.NumberFormats. Using NumberFormats, developers can read and modify number formats in documents, and also add new formats.

You have to retrieve the NumberFormatsSupplier as a property at a few objects from their com.sun.star.beans.XPropertySet interface, for example, from data sources supporting the com.sun.star.sdb.DataSource service and from database connections supporting the service com.sun.star.sdb.DatabaseEnvironment, or com.sun.star.sdb.DatabaseAccess. In addition, all UNO controls offering the service com.sun.star.awt.UnoControlFormattedFieldModel have a NumberFormatsSupplier property.

NumberFormats Service

The com.sun.star.util.NumberFormats service specifies a container of number formats and implements the interfaces com.sun.star.util.XNumberFormatTypes and com.sun.star.util.XNumberFormats.

XNumberFormats

NumberFormats supports the interface com.sun.star.util.XNumberFormats. This interface provides access to the number formats of a container. It is used to query the properties of a number format by an index key, retrieve a list of available number format keys of a given type for a given locale, query the key for a user-defined format string, or add new format codes into the list or to remove formats.

  com::sun::star::beans::XPropertySet getByKey ( [in] long nKey )
 
  sequence< long > queryKeys ( [in] short nType, 
                 [in] com::sun::star::lang::Locale nLocale, 
                 [in] boolean bCreate )
  long queryKey ( [in] string aFormat,
                 [in] com::sun::star::lang::Locale nLocale, 
                 [in] boolean bScan )
 
  long addNew ( [in] string aFormat, [in] com::sun::star::lang::Locale nLocale ) 
  long addNewConverted ( [in] string aFormat, [in] com::sun::star::lang::Locale nLocale, 
                 [in] com::sun::star::lang::Locale nNewLocale ) 
 
  void removeByKey ( [in] long nKey )
 
  string generateFormat ( [in] long nBaseKey, [in] com::sun::star::lang::Locale nLocale, 
                 [in] boolean bThousands, [in] boolean bRed, [in] short nDecimals, [in] short nLeading )

The important methods are probably queryKey() and addNew(). The method queryKey() finds the key for a given format string and locale, whereas addNew() creates a new format in the container and returns its key for immediate use. The bScan is reserved for future use and should be set to false.

The properties of a single number format are obtained by a call to getByKey() which returns a com.sun.star.util.NumberFormatProperties service for the given index key.

XNumberFormatTypes

The interface com.sun.star.util.XNumberFormatTypes offers functions to retrieve the index keys of specific predefined number format types. The predefined types are addressed by constants from com.sun.star.util.NumberFormat. The NumberFormat contains values for predefined format types, such as PERCENT, TIME, CURRENCY, and TEXT.

  long getStandardIndex ( [in] com::sun::star::lang::Locale nLocale )
  long getStandardFormat ( [in] short nType, 
                [in] com::sun::star::lang::Locale nLocale )
  long getFormatIndex ( [in] short nIndex, 
                [in] com::sun::star::lang::Locale nLocale )
 
  boolean isTypeCompatible ( [in] short nOldType, [in] short nNewType )
 
  long getFormatForLocale ( [in] long nKey, 
                [in] com::sun::star::lang::Locale nLocale )

In most cases you will need getStandardFormat(). It expects a type constant from the NumberFormat group and the locale to use, and returns the key of the corresponding predefined format.

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