icuSources/layoutex/layout/plruns.h

   1 /*
   2  *
   3  * (C) Copyright IBM Corp. 1998-2011 - All Rights Reserved
   4  *
   5  */
   6
   7 #ifndef __PLRUNS_H
   8 #define __PLRUNS_H
   9
  10 #include "unicode/utypes.h"
  11
  12 #ifndef U_HIDE_INTERNAL_API
  13
  14 #include "unicode/ubidi.h"
  15 #include "layout/LETypes.h"
  16
  17 #include "layout/loengine.h"
  18
  19 /**
  20  * Opaque datatype representing an array of font runs
  21  */
  22 typedef void pl_fontRuns;
  23 /**
  24  * Opaque datatype representing an array of value runs
  25  */
  26 typedef void pl_valueRuns;
  27 /**
  28  * Opaque datatype representing an array of locale runs
  29  */
  30 typedef void pl_localeRuns;
  31
  32 /**
  33  * \file
  34  * \brief C API for run arrays.
  35  *
  36  * This is a technology preview. The API may
  37  * change significantly.
  38  *
  39  */
  40
  41 /**
  42  * Construct a <code>pl_fontRuns</code> object from pre-existing arrays of fonts
  43  * and limit indices.
  44  *
  45  * @param fonts is the address of an array of pointers to <code>le_font</code> objects. This
  46  *              array, and the <code>le_font</code> objects to which it points must remain
  47  *              valid until the <code>pl_fontRuns</code> object is closed.
  48  *
  49  * @param limits is the address of an array of limit indices. This array must remain valid until
  50  *               the <code>pl_fontRuns</code> object is closed.
  51  *
  52  * @param count is the number of entries in the two arrays.
  53  *
  54  * @internal
  55  */
  56 U_INTERNAL pl_fontRuns * U_EXPORT2
  57 pl_openFontRuns(const le_font **fonts,
  58                 const le_int32 *limits,
  59                 le_int32 count);
  60
  61 /**
  62  * Construct an empty <code>pl_fontRuns</code> object. Clients can add font and limit
  63  * indices arrays using the <code>pl_addFontRun</code> routine.
  64  *
  65  * @param initialCapacity is the initial size of the font and limit indices arrays. If
  66  *                        this value is zero, no arrays will be allocated.
  67  *
  68  * @see pl_addFontRun
  69  *
  70  * @internal
  71  */
  72 U_INTERNAL pl_fontRuns * U_EXPORT2
  73 pl_openEmptyFontRuns(le_int32 initialCapacity);
  74
  75 /**
  76  * Close the given <code>pl_fontRuns</code> object. Once this
  77  * call returns, the object can no longer be referenced.
  78  *
  79  * @param fontRuns is the <code>pl_fontRuns</code> object.
  80  *
  81  * @internal
  82  */
  83 U_INTERNAL void U_EXPORT2
  84 pl_closeFontRuns(pl_fontRuns *fontRuns);
  85
  86 /**
  87  * Get the number of font runs.
  88  *
  89  * @param fontRuns is the <code>pl_fontRuns</code> object.
  90  *
  91  * @return the number of entries in the limit indices array.
  92  *
  93  * @internal
  94  */
  95 U_INTERNAL le_int32 U_EXPORT2
  96 pl_getFontRunCount(const pl_fontRuns *fontRuns);
  97
  98 /**
  99  * Reset the number of font runs to zero.
 100  *
 101  * @param fontRuns is the <code>pl_fontRuns</code> object.
 102  *
 103  * @internal
 104  */
 105 U_INTERNAL void U_EXPORT2
 106 pl_resetFontRuns(pl_fontRuns *fontRuns);
 107
 108 /**
 109  * Get the limit index for the last font run. This is the
 110  * number of characters in the text.
 111  *
 112  * @param fontRuns is the <code>pl_fontRuns</code> object.
 113  *
 114  * @return the last limit index.
 115  *
 116  * @internal
 117  */
 118 U_INTERNAL le_int32 U_EXPORT2
 119 pl_getFontRunLastLimit(const pl_fontRuns *fontRuns);
 120
 121 /**
 122  * Get the limit index for a particular font run.
 123  *
 124  * @param fontRuns is the <code>pl_fontRuns</code> object.
 125  * @param run is the run. This is an index into the limit index array.
 126  *
 127  * @return the limit index for the run, or -1 if <code>run</code> is out of bounds.
 128  *
 129  * @internal
 130  */
 131 U_INTERNAL le_int32 U_EXPORT2
 132 pl_getFontRunLimit(const pl_fontRuns *fontRuns,
 133                    le_int32 run);
 134
 135 /**
 136  * Get the <code>le_font</code> object assoicated with the given run
 137  * of text. Use <code>pl_getFontRunLimit(run)</code> to get the corresponding
 138  * limit index.
 139  *
 140  * @param fontRuns is the <code>pl_fontRuns</code> object.
 141  * @param run is the index into the font and limit indices arrays.
 142  *
 143  * @return the <code>le_font</code> associated with the given text run.
 144  *
 145  * @internal
 146  */
 147 U_INTERNAL const le_font * U_EXPORT2
 148 pl_getFontRunFont(const pl_fontRuns *fontRuns,
 149                   le_int32 run);
 150
 151
 152 /**
 153  * Add a new font run to the given <code>pl_fontRuns</code> object.
 154  *
 155  * If the <code>pl_fontRuns</code> object was not created by calling
 156  * <code>pl_openEmptyFontRuns</code>, this method will return a run index of -1.
 157  *
 158  * @param fontRuns is the <code>pl_fontRuns</code> object.
 159  *
 160  * @param font is the address of the <code>le_font</code> to add. This object must
 161  *             remain valid until the <code>pl_fontRuns</code> object is closed.
 162  *
 163  * @param limit is the limit index to add
 164  *
 165  * @return the run index where the font and limit index were stored, or -1 if
 166  *         the run cannot be added.
 167  *
 168  * @internal
 169  */
 170 U_INTERNAL le_int32 U_EXPORT2
 171 pl_addFontRun(pl_fontRuns *fontRuns,
 172               const le_font *font,
 173               le_int32 limit);
 174
 175 /**
 176  * Construct a <code>pl_valueRuns</code> object from pre-existing arrays of values
 177  * and limit indices.
 178  *
 179  * @param values is the address of an array of values. This array must remain valid until
 180                  the <code>pl_valueRuns</code> object is closed.
 181  *
 182  * @param limits is the address of an array of limit indices. This array must remain valid until
 183  *               the <code>pl_valueRuns</code> object is closed.
 184  *
 185  * @param count is the number of entries in the two arrays.
 186  *
 187  * @internal
 188  */
 189 U_INTERNAL pl_valueRuns * U_EXPORT2
 190 pl_openValueRuns(const le_int32 *values,
 191                  const le_int32 *limits,
 192                  le_int32 count);
 193
 194 /**
 195  * Construct an empty <code>pl_valueRuns</code> object. Clients can add values and limits
 196  * using the <code>pl_addValueRun</code> routine.
 197  *
 198  * @param initialCapacity is the initial size of the value and limit indices arrays. If
 199  *                        this value is zero, no arrays will be allocated.
 200  *
 201  * @see pl_addValueRun
 202  *
 203  * @internal
 204  */
 205 U_INTERNAL pl_valueRuns * U_EXPORT2
 206 pl_openEmptyValueRuns(le_int32 initialCapacity);
 207
 208 /**
 209  * Close the given <code>pl_valueRuns</code> object. Once this
 210  * call returns, the object can no longer be referenced.
 211  *
 212  * @param valueRuns is the <code>pl_valueRuns</code> object.
 213  *
 214  * @internal
 215  */
 216 U_INTERNAL void U_EXPORT2
 217 pl_closeValueRuns(pl_valueRuns *valueRuns);
 218
 219 /**
 220  * Get the number of value runs.
 221  *
 222  * @param valueRuns is the <code>pl_valueRuns</code> object.
 223  *
 224  * @return the number of value runs.
 225  *
 226  * @internal
 227  */
 228 U_INTERNAL le_int32 U_EXPORT2
 229 pl_getValueRunCount(const pl_valueRuns *valueRuns);
 230
 231 /**
 232  * Reset the number of value runs to zero.
 233  *
 234  * @param valueRuns is the <code>pl_valueRuns</code> object.
 235  *
 236  * @internal
 237  */
 238 U_INTERNAL void U_EXPORT2
 239 pl_resetValueRuns(pl_valueRuns *valueRuns);
 240
 241 /**
 242  * Get the limit index for the last value run. This is the
 243  * number of characters in the text.
 244  *
 245  * @param valueRuns is the <code>pl_valueRuns</code> object.
 246  *
 247  * @return the last limit index.
 248  *
 249  * @internal
 250  */
 251 U_INTERNAL le_int32 U_EXPORT2
 252 pl_getValueRunLastLimit(const pl_valueRuns *valueRuns);
 253
 254 /**
 255  * Get the limit index for a particular value run.
 256  *
 257  * @param valueRuns is the <code>pl_valueRuns</code> object.
 258  * @param run is the run index.
 259  *
 260  * @return the limit index for the run, or -1 if <code>run</code> is out of bounds.
 261  *
 262  * @internal
 263  */
 264 U_INTERNAL le_int32 U_EXPORT2
 265 pl_getValueRunLimit(const pl_valueRuns *valueRuns,
 266                      le_int32 run);
 267
 268 /**
 269  * Get the value assoicated with the given run * of text. Use
 270  * <code>pl_getValueRunLimit(run)</code> to get the corresponding
 271  * limit index.
 272  *
 273  * @param valueRuns is the <code>pl_valueRuns</code> object.
 274  * @param run is the run index.
 275  *
 276  * @return the value associated with the given text run.
 277  *
 278  * @internal
 279  */
 280 U_INTERNAL le_int32 U_EXPORT2
 281 pl_getValueRunValue(const pl_valueRuns *valueRuns,
 282                     le_int32 run);
 283
 284
 285 /**
 286  * Add a new font run to the given <code>pl_valueRuns</code> object.
 287  *
 288  * If the <code>pl_valueRuns</code> object was not created by calling
 289  * <code>pl_openEmptyFontRuns</code>, this method will return a run index of -1.
 290  *
 291  * @param valueRuns is the <code>pl_valueRuns</code> object.
 292  *
 293  * @param value is the value to add.
 294  *
 295  * @param limit is the limit index to add
 296  *
 297  * @return the run index where the font and limit index were stored, or -1 if
 298  *         the run cannot be added.
 299  *
 300  * @internal
 301  */
 302 U_INTERNAL le_int32 U_EXPORT2
 303 pl_addValueRun(pl_valueRuns *valueRuns,
 304                le_int32 value,
 305                le_int32 limit);
 306
 307 /**
 308  * Construct a <code>pl_localeRuns</code> object from pre-existing arrays of fonts
 309  * and limit indices.
 310  *
 311  * @param locales is the address of an array of pointers to locale name strings. This
 312  *                array must remain valid until the <code>pl_localeRuns</code> object is destroyed.
 313  *
 314  * @param limits is the address of an array of limit indices. This array must remain valid until
 315  *               the <code>pl_valueRuns</code> object is destroyed.
 316  *
 317  * @param count is the number of entries in the two arrays.
 318  *
 319  * @internal
 320  */
 321 U_INTERNAL pl_localeRuns * U_EXPORT2
 322 pl_openLocaleRuns(const char **locales,
 323                   const le_int32 *limits,
 324                   le_int32 count);
 325
 326 /**
 327  * Construct an empty <code>pl_localeRuns</code> object. Clients can add font and limit
 328  * indices arrays using the <code>pl_addFontRun</code> routine.
 329  *
 330  * @param initialCapacity is the initial size of the font and limit indices arrays. If
 331  *                        this value is zero, no arrays will be allocated.
 332  *
 333  * @see pl_addLocaleRun
 334  *
 335  * @internal
 336  */
 337 U_INTERNAL pl_localeRuns * U_EXPORT2
 338 pl_openEmptyLocaleRuns(le_int32 initialCapacity);
 339
 340 /**
 341  * Close the given <code>pl_localeRuns</code> object. Once this
 342  * call returns, the object can no longer be referenced.
 343  *
 344  * @param localeRuns is the <code>pl_localeRuns</code> object.
 345  *
 346  * @internal
 347  */
 348 U_INTERNAL void U_EXPORT2
 349 pl_closeLocaleRuns(pl_localeRuns *localeRuns);
 350
 351 /**
 352  * Get the number of font runs.
 353  *
 354  * @param localeRuns is the <code>pl_localeRuns</code> object.
 355  *
 356  * @return the number of entries in the limit indices array.
 357  *
 358  * @internal
 359  */
 360 U_INTERNAL le_int32 U_EXPORT2
 361 pl_getLocaleRunCount(const pl_localeRuns *localeRuns);
 362
 363 /**
 364  * Reset the number of locale runs to zero.
 365  *
 366  * @param localeRuns is the <code>pl_localeRuns</code> object.
 367  *
 368  * @internal
 369  */
 370 U_INTERNAL void U_EXPORT2
 371 pl_resetLocaleRuns(pl_localeRuns *localeRuns);
 372
 373 /**
 374  * Get the limit index for the last font run. This is the
 375  * number of characters in the text.
 376  *
 377  * @param localeRuns is the <code>pl_localeRuns</code> object.
 378  *
 379  * @return the last limit index.
 380  *
 381  * @internal
 382  */
 383 U_INTERNAL le_int32 U_EXPORT2
 384 pl_getLocaleRunLastLimit(const pl_localeRuns *localeRuns);
 385
 386 /**
 387  * Get the limit index for a particular font run.
 388  *
 389  * @param localeRuns is the <code>pl_localeRuns</code> object.
 390  * @param run is the run. This is an index into the limit index array.
 391  *
 392  * @return the limit index for the run, or -1 if <code>run</code> is out of bounds.
 393  *
 394  * @internal
 395  */
 396 U_INTERNAL le_int32 U_EXPORT2
 397 pl_getLocaleRunLimit(const pl_localeRuns *localeRuns,
 398                      le_int32 run);
 399
 400 /**
 401  * Get the <code>le_font</code> object assoicated with the given run
 402  * of text. Use <code>pl_getLocaleRunLimit(run)</code> to get the corresponding
 403  * limit index.
 404  *
 405  * @param localeRuns is the <code>pl_localeRuns</code> object.
 406  * @param run is the index into the font and limit indices arrays.
 407  *
 408  * @return the <code>le_font</code> associated with the given text run.
 409  *
 410  * @internal
 411  */
 412 U_INTERNAL const char * U_EXPORT2
 413 pl_getLocaleRunLocale(const pl_localeRuns *localeRuns,
 414                       le_int32 run);
 415
 416
 417 /**
 418  * Add a new run to the given <code>pl_localeRuns</code> object.
 419  *
 420  * If the <code>pl_localeRuns</code> object was not created by calling
 421  * <code>pl_openEmptyLocaleRuns</code>, this method will return a run index of -1.
 422  *
 423  * @param localeRuns is the <code>pl_localeRuns</code> object.
 424  *
 425  * @param locale is the name of the locale to add. This name must
 426  *               remain valid until the <code>pl_localeRuns</code> object is closed.
 427  *
 428  * @param limit is the limit index to add
 429  *
 430  * @return the run index where the font and limit index were stored, or -1 if
 431  *         the run cannot be added.
 432  *
 433  * @internal
 434  */
 435 U_INTERNAL le_int32 U_EXPORT2
 436 pl_addLocaleRun(pl_localeRuns *localeRuns,
 437                 const char *locale,
 438                 le_int32 limit);
 439
 440 #endif  /* U_HIDE_INTERNAL_API */
 441 #endif