source: golgotha/src/i4/string/string.txt @ 80

Last change on this file since 80 was 80, checked in by Sam Hocevar, 12 years ago
  • Adding the Golgotha source code. Not sure what's going to be interesting in there, but since it's all public domain, there's certainly stuff to pick up.
  • Property svn:keywords set to Id
File size: 3.3 KB
Line 
1Strings under I4 are perhaps one of the most complicated things to
2understand. 
3
4The main string classes are
5
6i4_const_str                    (strings which cannot be changed or freed)
7i4_str : public i4_const_str    (strings which can be changed and freed)
8
9i4_string_manager_class : public i4_init_class
10
11
12The primary goal of the string classes is to assist translations of
13products.  To enforce translation of all user visible strings, all
14strings must be created by a i4_string_manager_class which loads them
15from a resource file (while can be easily translated).  A resource
16file is a simple text file formatted as follows :
17
18internal external
19
20where is internal is the internal name referred to by the program.  The
21external name is the one the user sees and is might be translated.
22The string manager also supports arrays of strings as follows :
23
24internal { external1 external2 external3 external4 }
25
26optionally you can insert a = between the external and the external as
27follows :
28
29internal = external
30
31this assist parsing match up should you miss a word by accident.
32
33
34An i4_string_manager_class can load up strings from a file via
35load(i4_open_file_function_type opener, char *filename);
36(see files.txt for details about opener)
37
38Or it can load them up from a memory buffer (i.e. a resource file
39loaded into some memory location) with
40
41i4_bool load_buffer(i4_open_file_function_type opener,
42                    void *internal_buffer, char *error_prefix);
43
44
45Substitutions are allowed in resource files.
46
47internal1 = external1
48internal2 = ${external1}_external2
49
50Once strings have been loaded into a string_manager, then you can
51fetch them with either get or get_array. 
52
53i4_string_manager_class.get("internal2") returns
54i4_const_str("external1_external2")
55
56There is a global string manager defined for convince.
57i4_string_man.  Also the global function i4gets(char *) will
58fetch an external string from it using an internal name.
59
60font->put_string(screen, 10, 10, i4gets("name"), context);
61
62Internal symbol names are stored in a binary tree and a search
63is performed every time you call i4gets().
64
65The difference between i4_const_str and i4_str is that i4_const_str's
66are compacted into a small heap (head to toe) and cannot be freed or
67modified.  An i4_str resides in the main heap (allocated with
68i4_malloc). i4_str's can be deleted or modified.  An i4_str can be
69passed to routines needing i4_const_str because it is derived from it.
70i4_str's are usually constructed from i4_const_strs by insertion,
71concatenation, etc.  This ensures that all i4_str will built from
72parts that are translated, thus being translated themselves.
73
74Strings use iterators to access individual characters.  An iterator
75can be thought of as a pointer.  Incrementing moves to the next
76character, decrementing goes back one character.  i4_const_str.begin()
77returns an iterator referencing the first character in the string,
78while i4_const_str.end() returns an iterator referencing the last+1
79character in a string.  So you iterator through all the characters in
80a string if you want to.  This allows for addition of wide characters
81or kanji-escaped code characters without changes to the rest of the
82application.  (Neither are currently supported though).
83
84
Note: See TracBrowser for help on using the repository browser.