6.4. UNICODE

Open Inventor 8.0 now provides full Unicode support for file system methods, viewer methods, string manipulation and most strings displayed. New classes and methods have been added to existing classes to provide simple and efficient management functions for Unicode environments.

Unicode API

Open Inventor Unicode support is based on the SbString class, which has been extended to provide all the necessary manipulation methods to store, convert from and convert to a Unicode string representation.

There are new methods for:

  • Numeric values, i.e. setting a string from a number or converting a string to a number.

  • String conversion from or to utf8, utf16, WideChar and Latin-1 (ASCII).

  • String query functions like contains and find.

  • String splitting.

An SbString object can now be in one of three states:

  • null string: Represents an uninitialized string. The method isNull() returns TRUE if the string is null.

  • empty string: Represents a string that has been initialized but contains zero characters.

    The method isEmpty() returns TRUE if the string is empty (or null).

  • regular string: A Unicode or non Unicode string.

SbString stores Latin-1 (ASCII) strings in an std::string and stores Unicode strings in an std::wstring.

On Windows platforms wchar_t and unsigned short have the same size, but on Unix based platforms (including Mac OSX) a wchar_t is 4 bytes long. On Unix based systems, all Unicode strings are converted to utf16 when they are used in Qt or when they are written to an Inventor ASCII format file. It is transparent on Windows platforms.

Unicode File systems

The SbFileHelper SbFileHelper SbFileHelper class provides an easy way to abstract file name manipulation and allows platform independent support for Unicode file systems.

Using the standard fopen, open or STL functions can cause problems from a Unicode system point of view. We strongly recommend using SbFileHelper SbFileHelper SbFileHelper to handle file operations.

SbFileHelper SbFileHelper SbFileHelper allows:

  • Converting a UNIX path to and from a Microsoft Windows path.

  • Extracting the directory path, basename or extension from a fully qualified file path.

  • Checking if a file is accessible or not.

  • Generating a temporary filename.

  • Querying the size of a file.

Porting an application to a Unicode environment

All non-Unicode Open Inventor API methods now have a corresponding Unicode version. For example methods taking const char * parameters now have a corresponding SbString version.

The easiest way to port your code is to enable the OIV_UNICODE_CHECK C++ preprocessor definition or to define it at the top of the file you want to check for Unicode support.

e.g.:

#define OIV_UNICODE_CHECK

void func(void)
{
  SbString s("hello");

  printf( "%s", s.getString() );
}
  
          
        
          
        

This code will produce a warning because the function getString() is not Unicode compliant. The result of this method is ambiguous: is it regular ASCII text or utf8? A correct Unicode version of the source code above would use s.toLatin1() which returns an ASCII string.

Another example is the method SoInput SoInput SoInput ::openFile(). There are now two methods, one which takes a const char* and one which takes a const SbString & as the file name parameter. The SbString version is preferred because it can handle Unicode paths. Using the const char* version produces a warning when OIV_UNICODE_CHECK is set.

Qt based applications should always use the methods QString::utf16() or QString::fromUt16() to manage conversion from or to an SbString . The SbString class provides similar methods so it is easy to convert a QString to a SbString . This allows developing Unicode applications even on non-Unicode platforms. This is possible because Qt always uses utf16 format to store strings.