icuSources/layout/unicode/loengine.h

   1 /*
   2  *
   3  * (C) Copyright IBM Corp. 1998-2004 - All Rights Reserved
   4  *
   5  */
   6
   7 #ifndef __LOENGINE_H
   8 #define __LOENGINE_H
   9
  10 #include "unicode/utypes.h"
  11 #include "unicode/uobject.h"
  12 #include "unicode/uscript.h"
  13 #include "unicode/unistr.h"
  14
  15 #include "layout/LETypes.h"
  16 #include "layout/LayoutEngine.h"
  17
  18 U_NAMESPACE_BEGIN
  19
  20 /**
  21  * This is a wrapper class designed to allow ICU clients to
  22  * use LayoutEngine in a way that is consistent with the rest
  23  * of ICU.
  24  *
  25  * (LayoutEngine was developed seperately from ICU and
  26  * the same source is used in non-ICU environments, so it cannot
  27  * be changed to match ICU coding conventions).
  28  *
  29  * This class is designed for clients who wish to use LayoutEngine
  30  * to layout complex text. If you need to subclass LayoutEngine,
  31  * you'll need to use the LayoutEngine interfaces directly.
  32  *
  33  * Basically, it creates an instance of LayoutEngine, stashes
  34  * it in fLayoutEngine, and uses it to implement the layout
  35  * functionality.
  36  *
  37  * Use the createInstance method to create an ICULayoutEngine. Use
  38  * delete to destroy it. The layoutChars method computes the glyphs
  39  * and positions, and saves them in the ICULayoutEngine object.
  40  * Use getGlyphs, getPositions and getCharIndices to retreive this
  41  * data.
  42  *
  43  * You'll also need an implementation of LEFontInstance for your platform.
  44  *
  45  * @see LayoutEngine.h
  46  * @see LEFontInstance.h
  47  *
  48  * @obsolete ICU 3.0. Use LayoutEngine.h instead since this API will be removed in that release.
  49  */
  50 #ifndef U_HIDE_OBSOLETE_API
  51 class U_LAYOUT_API ICULayoutEngine : public UObject {
  52 private:
  53     /**
  54      * This holds the instance of LayoutEngine that does all
  55      * the work.
  56      */
  57     LayoutEngine *fLayoutEngine;
  58
  59     /**
  60      * This no argument constructor is private so that clients
  61      * can't envoke it. Clients should use createInstance.
  62      *
  63      * @see createInstance
  64      */
  65     ICULayoutEngine();
  66
  67     /**
  68      * The main constructor. It is defined as private to
  69      * stop clients from invoking it. Clients should use
  70      * createInstance.
  71      *
  72      * @param layoutEngine - the LayoutEngine that this instance wraps.
  73      *
  74      * @see createInstance
  75      */
  76     ICULayoutEngine(LayoutEngine *layoutEngine);
  77
  78 public:
  79
  80     /**
  81      * The destructor. At least on Windows it needs to be
  82      * virtual to ensure that it deletes the object from the
  83      * same heap that createInstance will allocate it from. We
  84      * don't know why this is...
  85      *
  86      * @see createInstance
  87      *
  88      * @obsolete ICU 3.0. Use LayoutEngine.h instead since this API will be removed in that release.
  89      */
  90     virtual ~ICULayoutEngine();
  91
  92     /**
  93      * This method computes the glyph, character index and position arrays
  94      * for the input characters.
  95      *
  96      * @param chars - the input character context
  97      * @param startOffset - the starting offset of the characters to process
  98      * @param endOffset - the ending offset of the characters to process
  99      * @param maxOffset - the number of characters in the input context
 100      * @param rightToLeft - TRUE if the characers are in a right to left directional run
 101      * @param x - the initial X position
 102      * @param y - the initial Y position
 103      * @param success - output parameter set to an error code if the operation fails
 104      *
 105      * @return the number of glyphs in the glyph array
 106      *
 107      * Note; the glyph, character index and position array can be accessed
 108      * using the getter method below.
 109      *
 110      * @obsolete ICU 3.0. Use LayoutEngine.h instead since this API will be removed in that release.
 111      */
 112     int32_t layoutChars(const UChar chars[],
 113                         int32_t startOffset,
 114                         int32_t endOffset,
 115                         int32_t maxOffset,
 116                         UBool rightToLeft,
 117                         float x, float y,
 118                         UErrorCode &success);
 119
 120
 121     /**
 122      * This method computes the glyph, character index and position arrays
 123      * for the input characters.
 124      *
 125      * @param str - the input character context
 126      * @param startOffset - the starting offset of the characters to process
 127      * @param endOffset - the ending offset of the characters to process
 128      * @param rightToLeft - TRUE if the characers are in a right to left directional run
 129      * @param x - the initial X position
 130      * @param y - the initial Y position
 131      * @param success - output parameter set to an error code if the operation fails
 132      *
 133      * @return the number of glyphs in the glyph array
 134      *
 135      * Note; the glyph, character index and position array can be accessed
 136      * using the getter method below.
 137      *
 138      * @obsolete ICU 3.0. Use LayoutEngine.h instead since this API will be removed in that release.
 139      */
 140     int32_t layoutString(const UnicodeString &str,
 141                          int32_t startOffset,
 142                          int32_t endOffset,
 143                          UBool rightToLeft,
 144                          float x, float y,
 145                          UErrorCode &success);
 146
 147     /**
 148      * This method returns the number of glyphs in the glyph array. Note
 149      * that the number of glyphs will be greater than or equal to the number
 150      * of characters used to create the LayoutEngine.
 151      *
 152      * @return the number of glyphs in the glyph array
 153      *
 154      * @obsolete ICU 3.0. Use LayoutEngine.h instead since this API will be removed in that release.
 155      */
 156     int32_t countGlyphs() const;
 157
 158     /**
 159      * This method copies the glyph array into a caller supplied array.
 160      * The caller must ensure that the array is large enough to hold all
 161      * the glyphs.
 162      *
 163      * @param glyphs - the destiniation glyph array
 164      * @param success - output parameter set to an error code if the operation fails
 165      *
 166      * @obsolete ICU 3.0. Use LayoutEngine.h instead since this API will be removed in that release.
 167      */
 168     void getGlyphs(uint32_t glyphs[], UErrorCode &success);
 169
 170     /**
 171      * This method copies the character index array into a caller supplied array.
 172      * The caller must ensure that the array is large enough to hold a character
 173      * index for each glyph.
 174      *
 175      * @param charIndices - the destiniation character index array
 176      * @param success - output parameter set to an error code if the operation fails
 177      *
 178      * @obsolete ICU 3.0. Use LayoutEngine.h instead since this API will be removed in that release.
 179      */
 180     void getCharIndices(int32_t charIndices[], UErrorCode &success);
 181
 182     /**
 183      * This method copies the character index array into a caller supplied array.
 184      * The caller must ensure that the array is large enough to hold a character
 185      * index for each glyph.
 186      *
 187      * @param charIndices - the destiniation character index array
 188      * @param indexBase - an offset which will be added to each index
 189      * @param success - output parameter set to an error code if the operation fails
 190      *
 191      * @obsolete ICU 3.0. Use LayoutEngine.h instead since this API will be removed in that release.
 192      */
 193     void getCharIndices(int32_t charIndices[], int32_t indexBase, UErrorCode &success);
 194
 195     /**
 196      * This method copies the position array into a caller supplied array.
 197      * The caller must ensure that the array is large enough to hold an
 198      * X and Y position for each glyph, plus an extra X and Y for the
 199      * advance of the last glyph.
 200      *
 201      * @param positions - the destiniation position array
 202      * @param success - output parameter set to an error code if the operation fails
 203      *
 204      * @obsolete ICU 3.0. Use LayoutEngine.h instead since this API will be removed in that release.
 205      */
 206     void getGlyphPositions(float positions[], UErrorCode &success);
 207
 208     /**
 209      * This method returns the X and Y position of the glyph at the
 210      * given index.
 211      *
 212      * Input parameters:
 213      * @param glyphIndex - the index of the glyph
 214      *
 215      * Output parameters:
 216      * @param x - the glyph's X position
 217      * @param y - the glyph's Y position
 218      * @param success - output parameter set to an error code if the operation fails
 219      *
 220      * @obsolete ICU 3.0. Use LayoutEngine.h instead since this API will be removed in that release.
 221      */
 222     void getGlyphPosition(int32_t glyphIndex, float &x, float &y, UErrorCode &success);
 223
 224     /**
 225      * This method returns an ICULayoutEngine capable of laying out text
 226      * in the given font, script and langauge.
 227      *
 228      * @param fontInstance - the font of the text
 229      * @param scriptCode - the script of the text
 230      * @param locale - used to determine the language of the text
 231      * @param success - output parameter set to an error code if the operation fails
 232      *
 233      * @return an ICULayoutEngine which can layout text in the given font.
 234      *
 235      * NOTE: currently, locale is ignored...
 236      *
 237      * @see LEFontInstance
 238      *
 239      * @obsolete ICU 3.0. Use LayoutEngine.h instead since this API will be removed in that release.
 240      */
 241     static ICULayoutEngine *createInstance(const LEFontInstance *fontInstance,
 242                                            UScriptCode scriptCode, Locale &locale,
 243                                            UErrorCode &success);
 244
 245     /**
 246      * ICU "poor man's RTTI", returns a UClassID for the actual class.
 247      *
 248      * @obsolete ICU 3.0. Use LayoutEngine.h instead since this API will be removed in that release.
 249      */
 250     virtual UClassID getDynamicClassID() const;
 251
 252     /**
 253      * ICU "poor man's RTTI", returns a UClassID for this class.
 254      *
 255      * @obsolete ICU 3.0. Use LayoutEngine.h instead since this API will be removed in that release.
 256      */
 257     static UClassID getStaticClassID();
 258 };
 259
 260 inline ICULayoutEngine::ICULayoutEngine()
 261 {
 262     // nothing at all...
 263 }
 264
 265 inline ICULayoutEngine::ICULayoutEngine(LayoutEngine *layoutEngine)
 266     : fLayoutEngine(layoutEngine)
 267 {
 268     // nothing else to do
 269 }
 270
 271 inline ICULayoutEngine::~ICULayoutEngine()
 272 {
 273     delete fLayoutEngine;
 274     fLayoutEngine = 0;
 275 }
 276
 277 inline int32_t ICULayoutEngine::layoutChars(const UChar chars[],
 278                                             int32_t startOffset,
 279                                             int32_t endOffset,
 280                                             int32_t maxOffset,
 281                                             UBool rightToLeft,
 282                                             float x, float y,
 283                                             UErrorCode &success)
 284 {
 285     // NOTE: call reset() so that clients can safely reuse
 286     fLayoutEngine->reset();
 287     return fLayoutEngine->layoutChars(chars,
 288                                       startOffset,
 289                                       endOffset - startOffset,
 290                                       maxOffset,
 291                                       rightToLeft,
 292                                       x, y,
 293                                       (LEErrorCode &) success);
 294 }
 295
 296 inline int32_t ICULayoutEngine::layoutString(const UnicodeString &str,
 297                                             int32_t startOffset,
 298                                             int32_t endOffset,
 299                                             UBool rightToLeft,
 300                                             float x, float y,
 301                                             UErrorCode &success)
 302 {
 303     // NOTE: call reset() so that clients can safely reuse
 304     fLayoutEngine->reset();
 305     return fLayoutEngine->layoutChars(str.getBuffer(),
 306                                       startOffset,
 307                                       endOffset - startOffset,
 308                                       str.length(),
 309                                       rightToLeft,
 310                                       x, y,
 311                                       (LEErrorCode &) success);
 312 }
 313
 314 inline int32_t ICULayoutEngine::countGlyphs() const
 315 {
 316     return fLayoutEngine->getGlyphCount();
 317 }
 318
 319 inline void ICULayoutEngine::getGlyphs(uint32_t glyphs[], UErrorCode &success)
 320 {
 321     fLayoutEngine->getGlyphs(glyphs, (LEErrorCode &) success);
 322 }
 323
 324 inline void ICULayoutEngine::getCharIndices(int32_t charIndices[], UErrorCode &success)
 325 {
 326     fLayoutEngine->getCharIndices(charIndices, (LEErrorCode &) success);
 327 }
 328
 329 inline void ICULayoutEngine::getCharIndices(int32_t charIndices[], int32_t indexBase, UErrorCode &success)
 330 {
 331     fLayoutEngine->getCharIndices(charIndices, indexBase, (LEErrorCode &) success);
 332 }
 333
 334 inline void ICULayoutEngine::getGlyphPositions(float positions[], UErrorCode &success)
 335 {
 336     fLayoutEngine->getGlyphPositions(positions, (LEErrorCode &) success);
 337 }
 338
 339 inline void ICULayoutEngine::getGlyphPosition(int32_t glyphIndex, float &x, float &y, UErrorCode &success)
 340 {
 341     fLayoutEngine->getGlyphPosition(glyphIndex, x, y, (LEErrorCode &) success);
 342 }
 343
 344 inline ICULayoutEngine *ICULayoutEngine::createInstance(const LEFontInstance *fontInstance,
 345                                                         UScriptCode scriptCode,
 346                                                         Locale &locale, UErrorCode &success)
 347 {
 348     LayoutEngine *engine = LayoutEngine::layoutEngineFactory(fontInstance,
 349                                                              (le_int32) scriptCode,
 350                                                              0,
 351                                                              (LEErrorCode &) success);
 352
 353     return new ICULayoutEngine(engine);
 354 }
 355 #endif // U_HIDE_OBSOLETE_API
 356
 357 U_NAMESPACE_END
 358 #endif