libs/FBidi.h

   1 /* -*-c-*- */
   2 /* Copyright (C) 2002 Mikhael Goikhman */
   3 /*
   4  * FBidi.h - interface to Bidi (bidirectionality for some asian languages).
   5  */
   6 /***
   7  * The main function is
   8  *   char *FBidiConvert(
   9  *     const char *logical_str, const char *charset, int str_len, Bool *is_rtl,
  10  *     int *out_len);
  11  *
  12  * input:
  13  *   logical string - the original string
  14  *   string charset - examples: "iso8859-15", "iso8859-8", "iso8859-6", "utf-8"
  15  *
  16  * output:
  17  *   visual string is returned (should be free'd), or NULL if not applicable
  18  *   the last argument is set to True if the string has the base RTL direction
  19  *
  20  * The is_rtl aggument may be used for 2 purposes. The first is to change the
  21  * string alignment if there is a free space (but it probably worth not to
  22  * override the user specified string aligment). The second is to determine
  23  * where to put ellipses if the string is longer than the available space.
  24  *
  25  * There are several possible ways to solve the ellipses problem.
  26  * This is not automated, the caller should choose one or another way.
  27  *
  28  * 1) For a logical string evaluate a visual string (and a base direction)
  29  *    only once. If needed, cut the visual string and add ellipses at the
  30  *    correct string side.
  31  *
  32  * 2) Cut logical string to the size that will be drawn, add allipses to the
  33  *    end and call FBidiConvert on the resulting string.
  34  *
  35  * 3) Cut logical string to the size that will be drawn, call FBidiConvert
  36  *    and add ellipses at the correct string side.
  37  *
  38  * Probably 2) is the best, but there is one nuance, the ellipses may be at
  39  * the middle of the string. With 1) and 3) the ellipses are always on the
  40  * edge of the string. The 1) is good when speed is more important than memory
  41  * and the string is usually either pure LTR or RTL.
  42  *
  43  * Example 1:
  44  *
  45  * input:  she said "SHALOM" and then "BOKER TOV".
  46  * output: she said "MOLAHS" and then "VOT REKOB".
  47  * is_rtl: False
  48  *
  49  * 1) she said "MO...
  50  * 2) she said ...HS"
  51  * 3) she said HS"...
  52  *
  53  * Example 2:
  54  *
  55  * input:  SHALOM, world!
  56  * output: !world ,MOLAHS
  57  * is_rtl: True
  58  *
  59  * 1) ...ld ,MOLAHS
  60  * 2) wo... ,MOLAHS
  61  * 3) ...wo ,MOLAHS
  62  *
  63  **/
  64
  65 #ifndef FBIDI_H
  66 #define FBIDI_H
  67
  68 #include "config.h"
  69 #include <X11/Xlib.h>
  70 #include "CombineChars.h"
  71
  72 #if HAVE_BIDI
  73 /*
  74  * Checks whether the string in the given charset should be BidiConvert'd.
  75  */
  76 Bool FBidiIsApplicable(const char *charset);
  77
  78 /*
  79  * Converts the given logical string to visual string for the given charset.
  80  */
  81 char *FBidiConvert(
  82         const char *logical_str, const char *charset, int str_len,
  83         Bool *is_rtl, int *out_len, superimpose_char_t *comb_chars,
  84         int *pos_l_to_v);
  85
  86 #else /* !HAVE_BIDI */
  87
  88 #define FBidiIsApplicable(c) False
  89
  90 #define FBidiConvert(s, c, l, r, o, cc, lv) NULL
  91
  92 #endif /* HAVE_BIDI */
  93
  94 #endif /* FBIDI_H */