1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
/* -*- Mode: C; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
#ifndef nsBidi_h__
#define nsBidi_h__
#include "unicode/ubidi.h"
#include "nsIFrame.h" // for nsBidiLevel/nsBidiDirection declarations
// nsBidi implemented as a simple wrapper around the bidi reordering engine
// from ICU.
// We could eliminate this and let callers use the ICU functions directly
// once we no longer care about building without ICU available.
class nsBidi
{
public:
/** @brief Default constructor.
*
* The nsBidi object is initially empty. It is assigned
* the Bidi properties of a paragraph by <code>SetPara()</code>.
*/
explicit nsBidi();
/** @brief Destructor. */
virtual ~nsBidi();
/**
* Perform the Unicode Bidi algorithm.
*
* @param aText is a pointer to the single-paragraph text that the
* Bidi algorithm will be performed on
* (step (P1) of the algorithm is performed externally).
* <strong>The text must be (at least) <code>aLength</code> long.</strong>
*
* @param aLength is the length of the text; if <code>aLength==-1</code> then
* the text must be zero-terminated.
*
* @param aParaLevel specifies the default level for the paragraph;
* it is typically 0 (LTR) or 1 (RTL).
* If the function shall determine the paragraph level from the text,
* then <code>aParaLevel</code> can be set to
* either <code>NSBIDI_DEFAULT_LTR</code>
* or <code>NSBIDI_DEFAULT_RTL</code>;
* if there is no strongly typed character, then
* the desired default is used (0 for LTR or 1 for RTL).
* Any other value between 0 and <code>NSBIDI_MAX_EXPLICIT_LEVEL</code>
* is also valid, with odd levels indicating RTL.
*/
nsresult SetPara(const char16_t *aText, int32_t aLength,
nsBidiLevel aParaLevel);
/**
* Get the directionality of the text.
*
* @param aDirection receives a <code>NSBIDI_XXX</code> value that indicates
* if the entire text represented by this object is unidirectional,
* and which direction, or if it is mixed-directional.
*
* @see nsBidiDirection
*/
nsresult GetDirection(nsBidiDirection* aDirection);
/**
* Get the paragraph level of the text.
*
* @param aParaLevel receives a <code>NSBIDI_XXX</code> value indicating
* the paragraph level
*
* @see nsBidiLevel
*/
nsresult GetParaLevel(nsBidiLevel* aParaLevel);
/**
* Get a logical run.
* This function returns information about a run and is used
* to retrieve runs in logical order.<p>
* This is especially useful for line-breaking on a paragraph.
*
* @param aLogicalStart is the first character of the run.
*
* @param aLogicalLimit will receive the limit of the run.
* The l-value that you point to here may be the
* same expression (variable) as the one for
* <code>aLogicalStart</code>.
* This pointer can be <code>nullptr</code> if this
* value is not necessary.
*
* @param aLevel will receive the level of the run.
* This pointer can be <code>nullptr</code> if this
* value is not necessary.
*/
nsresult GetLogicalRun(int32_t aLogicalStart, int32_t* aLogicalLimit,
nsBidiLevel* aLevel);
/**
* Get the number of runs.
* This function may invoke the actual reordering on the
* <code>nsBidi</code> object, after <code>SetPara</code>
* may have resolved only the levels of the text. Therefore,
* <code>CountRuns</code> may have to allocate memory,
* and may fail doing so.
*
* @param aRunCount will receive the number of runs.
*/
nsresult CountRuns(int32_t* aRunCount);
/**
* Get one run's logical start, length, and directionality,
* which can be 0 for LTR or 1 for RTL.
* In an RTL run, the character at the logical start is
* visually on the right of the displayed run.
* The length is the number of characters in the run.<p>
* <code>CountRuns</code> should be called
* before the runs are retrieved.
*
* @param aRunIndex is the number of the run in visual order, in the
* range <code>[0..CountRuns-1]</code>.
*
* @param aLogicalStart is the first logical character index in the text.
* The pointer may be <code>nullptr</code> if this index is not needed.
*
* @param aLength is the number of characters (at least one) in the run.
* The pointer may be <code>nullptr</code> if this is not needed.
*
* @param aDirection will receive the directionality of the run,
* <code>NSBIDI_LTR==0</code> or <code>NSBIDI_RTL==1</code>,
* never <code>NSBIDI_MIXED</code>.
*
* @see CountRuns<p>
*
* Example:
* @code
* int32_t i, count, logicalStart, visualIndex=0, length;
* nsBidiDirection dir;
* pBidi->CountRuns(&count);
* for(i=0; i<count; ++i) {
* pBidi->GetVisualRun(i, &logicalStart, &length, &dir);
* if(NSBIDI_LTR==dir) {
* do { // LTR
* show_char(text[logicalStart++], visualIndex++);
* } while(--length>0);
* } else {
* logicalStart+=length; // logicalLimit
* do { // RTL
* show_char(text[--logicalStart], visualIndex++);
* } while(--length>0);
* }
* }
* @endcode
*
* Note that in right-to-left runs, code like this places
* modifier letters before base characters and second surrogates
* before first ones.
*/
nsresult GetVisualRun(int32_t aRunIndex, int32_t* aLogicalStart,
int32_t* aLength, nsBidiDirection* aDirection);
/**
* This is a convenience function that does not use a nsBidi object.
* It is intended to be used for when an application has determined the levels
* of objects (character sequences) and just needs to have them reordered (L2).
* This is equivalent to using <code>GetVisualMap</code> on a
* <code>nsBidi</code> object.
*
* @param aLevels is an array with <code>aLength</code> levels that have been
* determined by the application.
*
* @param aLength is the number of levels in the array, or, semantically,
* the number of objects to be reordered.
* It must be <code>aLength>0</code>.
*
* @param aIndexMap is a pointer to an array of <code>aLength</code>
* indexes which will reflect the reordering of the characters.
* The array does not need to be initialized.<p>
* The index map will result in
* <code>aIndexMap[aVisualIndex]==aLogicalIndex</code>.
*/
static nsresult ReorderVisual(const nsBidiLevel* aLevels, int32_t aLength,
int32_t* aIndexMap);
protected:
UBiDi* mBiDi;
};
#endif // nsBidi_h__
|
