191 lines
6.8 KiB
C++
191 lines
6.8 KiB
C++
/* -*- 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__
|