Liblouis User's and Programmer's Manual

7.6 lou_translateString ¶

int lou_translateString(
  const char *tableList,
  const widechar *inbuf,
  int *inlen,
  widechar *outbuf,
  int *outlen,
  formtype *typeform,
  char *spacing,
  int mode);

This function takes a string of Unicode characters in inbuf and translates it into a string of characters in outbuf. Each character produces a particular dot pattern in one braille cell when sent to an embosser or braille display or to a screen type font. Which character represents which dot pattern is indicated by the character-definition and display opcodes in the translation table.

The tableList parameter points to a list of translation tables separated by commas. See How tables are found, for a description on how the tables are located in the file system. If only one table is given, no comma should be used after it. It is these tables which control just how the translation is made, whether in Grade 2, Grade 1, or something else.

The tables in a list are all compiled into the same internal table. The list is then regarded as the name of this table. As explained in How to Write Translation Tables, each table is a file which may be plain text, big-endian Unicode or little-endian Unicode. A table (or list of tables) is compiled into an internal representation the first time it is used. Liblouis keeps track of which tables have been compiled. For this reason, it is essential to call the lou_free function at the end of your application to avoid memory leaks. Do NOT call lou_free after each translation. This will force liblouis to compile the translation tables each time they are used, leading to great inefficiency.

Note that both the *inlen and *outlen parameters are pointers to integers. When the function is called, these integers contain the maximum input and output lengths, respectively. When it returns, they are set to the actual lengths used.

The typeform parameter is used to indicate italic type, boldface type, computer braille, etc. It is an array of formtype with the same length as the input buffer pointed to by *inbuf. However, it is used to pass back character-by-character results, so enough space must be provided to match the *outlen parameter. Each element indicates the typeform of the corresponding character in the input buffer. The values and their meaning can be consulted in the typeforms enum in liblouis.h. These values can be added for multiple emphasis. If this parameter is NULL, no checking for type forms is done. In addition, if this parameter is not NULL, it is set on return to have an 8 at every position corresponding to a character in outbuf which was defined to have a dot representation containing dot 7, dot 8 or both, and to 0 otherwise.

The spacing parameter is used to indicate differences in spacing between the input string and the translated output string. It is also of the same length as the string pointed to by *inbuf. If this parameter is NULL, no spacing information is computed.

The mode parameter specifies how the translation should be done. The valid values of mode are defined in liblouis.h. They are all powers of 2, so that a combined mode can be specified by adding up different values.

Note that the mode parameter is an integer, not a pointer to an integer.

A combination of the following mode flags can be used with the lou_translateString function:

compbrlAtCursor

If this bit is set in the mode parameter the space-bounded characters containing the cursor will be translated in computer braille.

compbrlLeftCursor

If this bit is set, only the characters to the left of the cursor will be in computer braille. This bit overrides compbrlAtCursor.

dotsIO

When this bit is set, during forward translation, Liblouis will produce output as dot patterns. During back-translation Liblouis accepts input as dot patterns. Note that the produced dot patterns are affected if you have any display opcode (see display) defined in any of your tables.

ucBrl

The ucBrl (Unicode Braille) bit is used by the functions lou_charToDots and lou_translate. It causes the dot patterns to be Unicode Braille rather than the liblouis representation. Note that you will not notice any change when setting ucBrl unless dotsIO is also set. lou_dotsToChar and lou_backTranslate recognize Unicode braille automatically.

partialTrans

This flag specifies that back-translation input should be treated as an incomplete word. Rules that apply only for complete words or at the end of a word will not take effect. This is intended to be used when translating input typed on a braille keyboard to provide a rough idea to the user of the characters they are typing before the word is complete.

noUndefined

Setting this bit disables the output of hexadecimal values when forward-translating undefined characters (characters that are not matched by any rule), and dot numbers when back-translating undefined braille patterns (braille patterns that are not matched by any rule). The default is for liblouis to output the hexadecimal value (as ’\xhhhh’) of an undefined character when forward-translating and the dot numbers (as \ddd/) of an undefined braille pattern when back-translating.

When back translating input from a braille keyboard cell by cell, it is desirable to output characters as soon as they are produced. Similarly, when back translating contracted braille, it is desirable to provide a "guess" to the user of the characters they typed. To achieve this, liblouis needs to have the ability to produce no text when indicators (which don’t produce a character by themselves) are not followed by another cell. This works automatically for indicators liblouis knows about such as capital sign, number sign, etc., but it does not work for indicators which are not (and cannot be) specifically defined as indicators. For example, in UEB, dots 4 5 6 alone produces the text "\456/". Setting the noUndefined mode suppresses this dot number output.

The function returns 1 if no errors were encountered² and 0 otherwise.