/builds/gitlab-kitware-sciviz-ci/Utilities/Doxygen/pages/StringEncoding.md
Go to the documentation of this file.
1 Implementation Details: String Encoding {#DesignStringEncoding}
2 =======================================
3 
4 This page summarizes the design details of string encoding in ParaView, which
5 covers pq to SM string call and SI to VTK / VTK to SI string arguments passing.
6 
7 ##Motivation##
8 
9 For a long time, ParaView used a simple implementation when passing string
10 arguments. pq Classes handles QString, which are a vory robust implementation
11 of string that need to be converted before being used as an actual c string.
12 For this conversion, ParaView used to use QString::toLatin1(), which works fine,
13 in order to pass the String to SM level.
14 Then on lower levels, all classes manipulate the same c string, without any
15 reencoding.
16 
17 This works fine most of the time, except in some cases, when the string
18 contains special characters. And it can happens a lot with filenames.
19 
20 They were two reasons for it not to work. First the client/server communication
21 is done via a library called protobuf, which support only UTF8 string.
22 Second, Latin1 is a specific encoding, which can be different from the
23 local 8 Bits encoding of strings.
24 
25 Special character are now supported in filenames in ParaView, and
26 one should take care of conversion when handling filenames.
27 
28 ##Design##
29 
30 Once the problem is understood, the design is quite simple.
31 QString in pq classes given as an argument of non-pq classes should be encoded
32 to local 8 bit encoding when used locally.
33 QString in pq classes given as an argument of SM classes that will transfer it to the server
34 should be encoded to utf8.
35 In SI classes, string should then reencoded to local 8 bit before being given to vtk classes
36 SI classes recovering string from vtk classes should re-encode string in utf8.
37 
38 ##Usage##
39 
40 When developping a new feature, especially a Qt feature handling filenames, one should
41 use the following pattern :
42  * Filename QString that need to be converted to c-string and used **locally** should be encoded
43 using **QString::toLocal8Bit**.
44  * Filename QString that need to be converted to c-string and **transferred to the server**
45 should be encoded using **QString::toUtf8**.
46  * All **other** QString should be converted **using QString::toUtf8** unless specific reasons.
47 
48 The server side is done automatically for filename StringVectorProperty, and a few other cases.
49 
50 Notes
51 ------
52 This page is generated from *StringEncoding.md*.