Right to Left Text Support

Scaleform supports rendering right-to-left (RTL) text. RTL text rendering is used for Arabic and Hebrew languages. There are several limitations to the RTL text support in Scaleform:

• Editing and selection of RTL text is not supported;
• Some text position-related functions do not work correctly, such as getCharBoundaries();
• Arabic shaping (changing letter's glyph depending on where the letter is located ) is not implemented, but it is possible for customer to implement his own algorithm via Translator::OnBidirectionalText callback (see below for details).
• Arabic ligaturing is not implemented, but it is possible for customer to implement his own algorithm via Translator::OnBidirectionalText callback (see below for details).
• Mirroring is not implemented, but it is possible for customer to implement his own algorithm via Translator::OnBidirectionalText callback (see below for details). Currently, mirroring can be implemented only by replacing one glyph by another (for example ']' can be replaced by '['). If there is no corresponding mirrored glyph in the font then currently mirroring for such glyphs is not possible (for example, the integral math symbol).

To enable RTL text rendering the following should be done:

• Scaleform should be compiled with option GFX_ENABLE_BIDIRECTIONAL_TEXT enabled in GFxConfig.h (it is so by default);

• Inherit from Translator class and override GetCaps method to return 'Cap_BidirectionalText' flag, for example:

  #include "GFx_Loader.h"
  
  class Translator : public SF::GFx::Translator
  {
  public:
       virtual unsigned GetCaps() const { return Cap_BidirectionalText; }
  };

• Create an instance of the custom Translator class and set it to the Loader object:

  SF:GFx::Loader loader;
  ...
  loader.SetTranslator(Ptr<SF:GFx::Translator>(*new Translator()));

Scaleform contains basic implementation of RTL text re-ordering. It is able to re-order mixed RTL and ordinary text correctly. However, the algorithm is not fully Unicode-complaint. User can re-implement re-ordering algorithm by overriding the Translator::OnBidirectionalText virtual method. This method can be also used to implement re-shaping, ligaturing and mirroring (with some limitations discussed earlier). The signature of OnBidirectionalText is the following:

virtual bool OnBidirectionalText(const wchar_t* text, UPInt textLen, wchar_t* newText, 
                                 unsigned* indexMap, bool* mirrorBits);

This method is called once per paragraph when bidirectional text is detected (Arabic or Hebrew) and if support of bidirectional text is enabled (see above). The 'paragraphs' are text lines separated by new-line symbols.

This method receives 'text' (a wchar_t pointer to the paragraph text) and 'textLen' (the number of characters in the 'text') as input parameters. The 'newText', 'indexMap' and 'mirrorBits' parameters are just pre-allocated buffers to fill out. The sizes of these buffers are textLen*sizeof(type).

The 'newText' should receive changed text: it should be re-ordered and optionally re-shaped/ligatured/mirrored. To implement re-shaping / ligaturing user should replace codes from 'text' by the codes corresponding to the desired form. New codes should be put into 'newText' buffer. For example, the letter with code 0x621 might be replaced by code 0xFE87, if this letter is in the middle of the word. Similarly, the character '[' might be replaced by ']' for mirroring.

The 'indexMap' array should contain mappings between old (original) and new (re-ordered) indices. The index in this array represents indices of characters in the original 'text'. The values at the indices represent new locations of the characters. For example, if original character at index 0 was relocated to index 10, then indexMap[0] = 10. It is very important to fill this array correctly, otherwise ASSERT may be thrown in Text::DocView::CheckConsistency method.

'mirrorBits' is an array of booleans, where each element represents corresponding position in the re-ordered text; if the element is set to 'true' then the glyph should be rendered mirrored. Not supported yet.

This method should return 'true' if method was successful and the core should use contents of the buffers; false, if no changes to the text field should be applied.