1/* 2 * Copyright (c) 2024 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17 * @file 18 * @kit ArkGraphics2D 19 */ 20import type drawing from './@ohos.graphics.drawing'; 21import type common2D from './@ohos.graphics.common2D'; 22/*** if arkts 1.2 */ 23import { Resource } from './global/resource'; 24/*** endif */ 25 26/** 27 * The Text module provides a set of APIs for text layout and font management. 28 * It aims to deliver high-quality typesetting through features like character-to-glyph 29 * conversion, kerning, line breaking, alignment, and text measurement. Additionally, 30 * it provides font management capabilities, including font registration, font descriptors, 31 * and font collection management. 32 * 33 * This module provides the following classes for creating complex text paragraphs: 34 * 35 * TextStyle: defines the font type, size, spacing, and other text properties. 36 * FontCollection: manages a collection of different fonts. 37 * FontDescriptor: provides information about font descriptors. 38 * ParagraphStyle: controls line break and word break strategies for the entire paragraph. 39 * ParagraphBuilder: used to create different paragraph objects. 40 * Paragraph: created by calling build() of the ParagraphBuilder class. 41 * LineTypeset: created by calling buildLineTypeset() of the ParagraphBuilder class. 42 * TextLine: paragraph text on a line-by-line basis, obtained by calling getTextLines() of the Paragraph class. 43 * Run: text typesetting unit, obtained by calling getGlyphRuns() of the TextLine class. 44 * 45 * @namespace text 46 * @syscap SystemCapability.Graphics.Drawing 47 * @since arkts {'1.1':'12','1.2':'20'} 48 * @arkts 1.1&1.2 49 */ 50declare namespace text { 51 52 /** 53 * Refers to how to align the horizontal position of text when displaying text. 54 * @enum { number } 55 * @syscap SystemCapability.Graphics.Drawing 56 * @since arkts {'1.1':'12','1.2':'20'} 57 * @arkts 1.1&1.2 58 */ 59 enum TextAlign { 60 /** 61 * Use the left side of the text as a reference line for alignment. 62 * @syscap SystemCapability.Graphics.Drawing 63 * @since arkts {'1.1':'12','1.2':'20'} 64 * @arkts 1.1&1.2 65 */ 66 LEFT = 0, 67 68 /** 69 * Use the right side of the text as a reference line for alignment. 70 * @syscap SystemCapability.Graphics.Drawing 71 * @since arkts {'1.1':'12','1.2':'20'} 72 * @arkts 1.1&1.2 73 */ 74 RIGHT = 1, 75 76 /** 77 * Use the midpoint line the text as a reference line for alignment. 78 * @syscap SystemCapability.Graphics.Drawing 79 * @since arkts {'1.1':'12','1.2':'20'} 80 * @arkts 1.1&1.2 81 */ 82 CENTER = 2, 83 84 /** 85 * Justified, which means that each line (except the last line) is stretched so that every line has equal width, 86 * and the left and right margins are straight. 87 * @syscap SystemCapability.Graphics.Drawing 88 * @since arkts {'1.1':'12','1.2':'20'} 89 * @arkts 1.1&1.2 90 */ 91 JUSTIFY = 3, 92 93 /** 94 * Align text from start, based on the TextDirection, such as left-to-right or right-to-left. 95 * @syscap SystemCapability.Graphics.Drawing 96 * @since arkts {'1.1':'12','1.2':'20'} 97 * @arkts 1.1&1.2 98 */ 99 START = 4, 100 101 /** 102 * Align text from end, based on the TextDirection, such as left-to-right or right-to-left, opposite to START. 103 * @syscap SystemCapability.Graphics.Drawing 104 * @since arkts {'1.1':'12','1.2':'20'} 105 * @arkts 1.1&1.2 106 */ 107 END = 5, 108 } 109 110 /** 111 * Enumerates the vertical alignment modes. 112 * @enum { number } 113 * @syscap SystemCapability.Graphics.Drawing 114 * @since 20 115 */ 116 enum TextVerticalAlign { 117 /** 118 * Baseline alignment in the vertical direction. 119 * @syscap SystemCapability.Graphics.Drawing 120 * @since 20 121 */ 122 BASELINE = 0, 123 /** 124 * Bottom alignment in the vertical direction. 125 * @syscap SystemCapability.Graphics.Drawing 126 * @since 20 127 */ 128 BOTTOM = 1, 129 /** 130 * Center alignment in the vertical direction. 131 * @syscap SystemCapability.Graphics.Drawing 132 * @since 20 133 */ 134 CENTER = 2, 135 /** 136 * Top alignment in the vertical direction. 137 * @syscap SystemCapability.Graphics.Drawing 138 * @since 20 139 */ 140 TOP = 3 141 } 142 143 /** 144 * Enumerate text runs direction. 145 * @enum { number } 146 * @syscap SystemCapability.Graphics.Drawing 147 * @since arkts {'1.1':'12','1.2':'20'} 148 * @arkts 1.1&1.2 149 */ 150 enum TextDirection { 151 /** 152 * The text is oriented from right to left. 153 * @syscap SystemCapability.Graphics.Drawing 154 * @since arkts {'1.1':'12','1.2':'20'} 155 * @arkts 1.1&1.2 156 */ 157 RTL, 158 159 /** 160 * The text is oriented from left to right. 161 * @syscap SystemCapability.Graphics.Drawing 162 * @since arkts {'1.1':'12','1.2':'20'} 163 * @arkts 1.1&1.2 164 */ 165 LTR, 166 } 167 168 /** 169 * Enumerate text segmentation strategy. 170 * @enum { number } 171 * @syscap SystemCapability.Graphics.Drawing 172 * @since arkts {'1.1':'12','1.2':'20'} 173 * @arkts 1.1&1.2 174 */ 175 enum BreakStrategy { 176 /** 177 * Fills the current line as much as possible without adding hyphens. 178 * @syscap SystemCapability.Graphics.Drawing 179 * @since arkts {'1.1':'12','1.2':'20'} 180 * @arkts 1.1&1.2 181 */ 182 GREEDY, 183 184 /** 185 * Optimizes layout and may add hyphens when necessary. 186 * @syscap SystemCapability.Graphics.Drawing 187 * @since arkts {'1.1':'12','1.2':'20'} 188 * @arkts 1.1&1.2 189 */ 190 HIGH_QUALITY, 191 192 /** 193 * Ensures consistent line width in a paragraph, adding hyphens if needed. 194 * @syscap SystemCapability.Graphics.Drawing 195 * @since arkts {'1.1':'12','1.2':'20'} 196 * @arkts 1.1&1.2 197 */ 198 BALANCED, 199 } 200 201 /** 202 * Enumerate word break strategy. 203 * @enum { number } 204 * @syscap SystemCapability.Graphics.Drawing 205 * @since arkts {'1.1':'12','1.2':'20'} 206 * @arkts 1.1&1.2 207 */ 208 enum WordBreak { 209 /** 210 * Default mode that break words based on language-specific conventions. 211 * @syscap SystemCapability.Graphics.Drawing 212 * @since arkts {'1.1':'12','1.2':'20'} 213 * @arkts 1.1&1.2 214 */ 215 NORMAL, 216 217 /** 218 * Allows breaks within any character in non-CJK text. (CJK means Chinese, Japanese, and Korean.) 219 * This value is suitable for Asian text that contains some non-Asian text. For example, 220 * it can be used to break consecutive English characters. 221 * @syscap SystemCapability.Graphics.Drawing 222 * @since arkts {'1.1':'12','1.2':'20'} 223 * @arkts 1.1&1.2 224 */ 225 BREAK_ALL, 226 227 /** 228 * Allows breaks between any two characters in non-CJK text. It prioritizes breaking at whitespace 229 * or other natural breakpoints to keep words intact. If no breakpoints are found, it breaks between 230 * any two characters. For CJK text, this behaves like NORMAL. 231 * @syscap SystemCapability.Graphics.Drawing 232 * @since arkts {'1.1':'12','1.2':'20'} 233 * @arkts 1.1&1.2 234 */ 235 BREAK_WORD, 236 237 /** 238 * Attempts to break words at the end of a line using a hyphen. If a hyphen cannot be added, 239 * it behaves like BREAK_WORD. 240 * @syscap SystemCapability.Graphics.Drawing 241 * @since arkts {'1.1':'18','1.2':'20'} 242 * @arkts 1.1&1.2 243 */ 244 BREAK_HYPHEN, 245 } 246 247 /** 248 * Describes a text decoration. 249 * @typedef Decoration 250 * @syscap SystemCapability.Graphics.Drawing 251 * @since arkts {'1.1':'12','1.2':'20'} 252 * @arkts 1.1&1.2 253 */ 254 interface Decoration { 255 /** 256 * Type of the decoration. The default value is NONE. 257 * @type { ?TextDecorationType } 258 * @syscap SystemCapability.Graphics.Drawing 259 * @since arkts {'1.1':'12','1.2':'20'} 260 * @arkts 1.1&1.2 261 */ 262 textDecoration?: TextDecorationType; 263 264 /** 265 * Color of the decoration. The default value is transparent. 266 * @type { ?common2D.Color } 267 * @syscap SystemCapability.Graphics.Drawing 268 * @since arkts {'1.1':'12','1.2':'20'} 269 * @arkts 1.1&1.2 270 */ 271 color?: common2D.Color; 272 273 /** 274 * Style of the decoration. The default value is SOLID. 275 * @type { ?TextDecorationStyle } 276 * @syscap SystemCapability.Graphics.Drawing 277 * @since arkts {'1.1':'12','1.2':'20'} 278 * @arkts 1.1&1.2 279 */ 280 decorationStyle?: TextDecorationStyle; 281 282 /** 283 * Scale factor for the thickness of the decoration line. The value is a floating point number. 284 * The default value is 1.0. 285 * @type { ?number } 286 * @syscap SystemCapability.Graphics.Drawing 287 * @since arkts {'1.1':'12','1.2':'20'} 288 * @arkts 1.1&1.2 289 */ 290 decorationThicknessScale?: number; 291 } 292 293 /** 294 * Enumerates the text decoration types. 295 * @enum { number } 296 * @syscap SystemCapability.Graphics.Drawing 297 * @since arkts {'1.1':'12','1.2':'20'} 298 * @arkts 1.1&1.2 299 */ 300 enum TextDecorationType { 301 /** 302 * There are no text decoration. 303 * @syscap SystemCapability.Graphics.Drawing 304 * @since arkts {'1.1':'12','1.2':'20'} 305 * @arkts 1.1&1.2 306 */ 307 NONE, 308 309 /** 310 * There is a decoration line below the text. 311 * @syscap SystemCapability.Graphics.Drawing 312 * @since arkts {'1.1':'12','1.2':'20'} 313 * @arkts 1.1&1.2 314 */ 315 UNDERLINE, 316 317 /** 318 * There is a decoration line above the text. 319 * @syscap SystemCapability.Graphics.Drawing 320 * @since arkts {'1.1':'12','1.2':'20'} 321 * @arkts 1.1&1.2 322 */ 323 OVERLINE, 324 325 /** 326 * There is a decoration line through the middle of the text. 327 * @syscap SystemCapability.Graphics.Drawing 328 * @since arkts {'1.1':'12','1.2':'20'} 329 * @arkts 1.1&1.2 330 */ 331 LINE_THROUGH, 332 } 333 334 /** 335 * Enumerates the text decoration styles. 336 * @enum { number } 337 * @syscap SystemCapability.Graphics.Drawing 338 * @since arkts {'1.1':'12','1.2':'20'} 339 * @arkts 1.1&1.2 340 */ 341 enum TextDecorationStyle { 342 /** 343 * Decoration line is solid line. 344 * @syscap SystemCapability.Graphics.Drawing 345 * @since arkts {'1.1':'12','1.2':'20'} 346 * @arkts 1.1&1.2 347 */ 348 SOLID, 349 350 /** 351 * Decoration line is double line. 352 * @syscap SystemCapability.Graphics.Drawing 353 * @since arkts {'1.1':'12','1.2':'20'} 354 * @arkts 1.1&1.2 355 */ 356 DOUBLE, 357 358 /** 359 * Decoration line is dotted line. 360 * @syscap SystemCapability.Graphics.Drawing 361 * @since arkts {'1.1':'12','1.2':'20'} 362 * @arkts 1.1&1.2 363 */ 364 DOTTED, 365 366 /** 367 * Decoration line is dashed line. 368 * @syscap SystemCapability.Graphics.Drawing 369 * @since arkts {'1.1':'12','1.2':'20'} 370 * @arkts 1.1&1.2 371 */ 372 DASHED, 373 374 /** 375 * Decoration line is wavy line. 376 * @syscap SystemCapability.Graphics.Drawing 377 * @since arkts {'1.1':'12','1.2':'20'} 378 * @arkts 1.1&1.2 379 */ 380 WAVY, 381 } 382 383 /** 384 * Enumeration of font weight of text. 385 * @enum { number } 386 * @syscap SystemCapability.Graphics.Drawing 387 * @since arkts {'1.1':'12','1.2':'20'} 388 * @arkts 1.1&1.2 389 */ 390 enum FontWeight { 391 /** 392 * Thin 393 * @syscap SystemCapability.Graphics.Drawing 394 * @since arkts {'1.1':'12','1.2':'20'} 395 * @arkts 1.1&1.2 396 */ 397 W100, 398 399 /** 400 * Extra-light 401 * @syscap SystemCapability.Graphics.Drawing 402 * @since arkts {'1.1':'12','1.2':'20'} 403 * @arkts 1.1&1.2 404 */ 405 W200, 406 407 /** 408 * Light 409 * @syscap SystemCapability.Graphics.Drawing 410 * @since arkts {'1.1':'12','1.2':'20'} 411 * @arkts 1.1&1.2 412 */ 413 W300, 414 415 /** 416 * Normal/Regular 417 * @syscap SystemCapability.Graphics.Drawing 418 * @since arkts {'1.1':'12','1.2':'20'} 419 * @arkts 1.1&1.2 420 */ 421 W400, 422 423 /** 424 * Medium 425 * @syscap SystemCapability.Graphics.Drawing 426 * @since arkts {'1.1':'12','1.2':'20'} 427 * @arkts 1.1&1.2 428 */ 429 W500, 430 431 /** 432 * Semi-bold 433 * @syscap SystemCapability.Graphics.Drawing 434 * @since arkts {'1.1':'12','1.2':'20'} 435 * @arkts 1.1&1.2 436 */ 437 W600, 438 439 /** 440 * Bold 441 * @syscap SystemCapability.Graphics.Drawing 442 * @since arkts {'1.1':'12','1.2':'20'} 443 * @arkts 1.1&1.2 444 */ 445 W700, 446 447 /** 448 * Extra-bold 449 * @syscap SystemCapability.Graphics.Drawing 450 * @since arkts {'1.1':'12','1.2':'20'} 451 * @arkts 1.1&1.2 452 */ 453 W800, 454 455 /** 456 * Black 457 * @syscap SystemCapability.Graphics.Drawing 458 * @since arkts {'1.1':'12','1.2':'20'} 459 * @arkts 1.1&1.2 460 */ 461 W900, 462 } 463 464 /** 465 * Enumeration of font style of text. 466 * @enum { number } 467 * @syscap SystemCapability.Graphics.Drawing 468 * @since arkts {'1.1':'12','1.2':'20'} 469 * @arkts 1.1&1.2 470 */ 471 enum FontStyle { 472 /** 473 * Upright font type. 474 * @syscap SystemCapability.Graphics.Drawing 475 * @since arkts {'1.1':'12','1.2':'20'} 476 * @arkts 1.1&1.2 477 */ 478 NORMAL, 479 480 /** 481 * Slant font. If no italic version is available for the current font, the oblique version will be used instead. 482 * @syscap SystemCapability.Graphics.Drawing 483 * @since arkts {'1.1':'12','1.2':'20'} 484 * @arkts 1.1&1.2 485 */ 486 ITALIC, 487 488 /** 489 * Oblique font. If no oblique version is available for the current font, the italic version will be used instead. 490 * @syscap SystemCapability.Graphics.Drawing 491 * @since arkts {'1.1':'12','1.2':'20'} 492 * @arkts 1.1&1.2 493 */ 494 OBLIQUE, 495 } 496 497 /** 498 * Enumeration of font width of text. 499 * @enum { number } 500 * @syscap SystemCapability.Graphics.Drawing 501 * @since arkts {'1.1':'12','1.2':'20'} 502 * @arkts 1.1&1.2 503 */ 504 enum FontWidth { 505 /** 506 * Ultra condensed font width. 507 * @syscap SystemCapability.Graphics.Drawing 508 * @since arkts {'1.1':'12','1.2':'20'} 509 * @arkts 1.1&1.2 510 */ 511 ULTRA_CONDENSED = 1, 512 513 /** 514 * Extra condensed font width. 515 * @syscap SystemCapability.Graphics.Drawing 516 * @since arkts {'1.1':'12','1.2':'20'} 517 * @arkts 1.1&1.2 518 */ 519 EXTRA_CONDENSED = 2, 520 521 /** 522 * Condensed font width. 523 * @syscap SystemCapability.Graphics.Drawing 524 * @since arkts {'1.1':'12','1.2':'20'} 525 * @arkts 1.1&1.2 526 */ 527 CONDENSED = 3, 528 529 /** 530 * Semi condensed font width. 531 * @syscap SystemCapability.Graphics.Drawing 532 * @since arkts {'1.1':'12','1.2':'20'} 533 * @arkts 1.1&1.2 534 */ 535 SEMI_CONDENSED = 4, 536 537 /** 538 * Normal font width. 539 * @syscap SystemCapability.Graphics.Drawing 540 * @since arkts {'1.1':'12','1.2':'20'} 541 * @arkts 1.1&1.2 542 */ 543 NORMAL = 5, 544 545 /** 546 * Semi expanded font width. 547 * @syscap SystemCapability.Graphics.Drawing 548 * @since arkts {'1.1':'12','1.2':'20'} 549 * @arkts 1.1&1.2 550 */ 551 SEMI_EXPANDED = 6, 552 553 /** 554 * Expanded font width. 555 * @syscap SystemCapability.Graphics.Drawing 556 * @since arkts {'1.1':'12','1.2':'20'} 557 * @arkts 1.1&1.2 558 */ 559 EXPANDED = 7, 560 561 /** 562 * Extra expanded font width. 563 * @syscap SystemCapability.Graphics.Drawing 564 * @since arkts {'1.1':'12','1.2':'20'} 565 * @arkts 1.1&1.2 566 */ 567 EXTRA_EXPANDED = 8, 568 569 /** 570 * Ultra expanded font width. 571 * @syscap SystemCapability.Graphics.Drawing 572 * @since arkts {'1.1':'12','1.2':'20'} 573 * @arkts 1.1&1.2 574 */ 575 ULTRA_EXPANDED = 9, 576 } 577 578 /** 579 * Enumerates the text height modifier patterns. 580 * @enum { number } 581 * @syscap SystemCapability.Graphics.Drawing 582 * @since arkts {'1.1':'12','1.2':'20'} 583 * @arkts 1.1&1.2 584 */ 585 enum TextHeightBehavior { 586 /** 587 * Allows the first line of the paragraph to rise and the last line to drop. 588 * @syscap SystemCapability.Graphics.Drawing 589 * @since arkts {'1.1':'12','1.2':'20'} 590 * @arkts 1.1&1.2 591 */ 592 ALL = 0x0, 593 594 /** 595 * Prevents the first line of a paragraph from rising. 596 * @syscap SystemCapability.Graphics.Drawing 597 * @since arkts {'1.1':'12','1.2':'20'} 598 * @arkts 1.1&1.2 599 */ 600 DISABLE_FIRST_ASCENT = 0x1, 601 602 /** 603 * Prevents the last line of a paragraph from dropping. 604 * @syscap SystemCapability.Graphics.Drawing 605 * @since arkts {'1.1':'12','1.2':'20'} 606 * @arkts 1.1&1.2 607 */ 608 DISABLE_LAST_ASCENT = 0x2, 609 610 /** 611 * Combines the effects of disabling the first line from rising and the last line from dropping. 612 * @syscap SystemCapability.Graphics.Drawing 613 * @since arkts {'1.1':'12','1.2':'20'} 614 * @arkts 1.1&1.2 615 */ 616 DISABLE_ALL = 0x1 | 0x2, 617 } 618 619 /** 620 * Enumeration the type of text baseline. 621 * @enum { number } 622 * @syscap SystemCapability.Graphics.Drawing 623 * @since arkts {'1.1':'12','1.2':'20'} 624 * @arkts 1.1&1.2 625 */ 626 enum TextBaseline { 627 /** 628 * The alphabetic baseline, typically used for Latin-based scripts where the baseline aligns 629 * with the base of lowercase letters. 630 * @syscap SystemCapability.Graphics.Drawing 631 * @since arkts {'1.1':'12','1.2':'20'} 632 * @arkts 1.1&1.2 633 */ 634 ALPHABETIC, 635 636 /** 637 * The ideographic baseline, commonly used for ideographic scripts such as Chinese, Japanese, and Korean, 638 * where the baseline aligns with the center of characters. 639 * @syscap SystemCapability.Graphics.Drawing 640 * @since arkts {'1.1':'12','1.2':'20'} 641 * @arkts 1.1&1.2 642 */ 643 IDEOGRAPHIC, 644 } 645 646 /** 647 * Enumerates of ellipsis mode. 648 * EllipsisMode.START and EllipsisMode.MIDDLE take effect only when text overflows in a single line. 649 * @enum { number } 650 * @syscap SystemCapability.Graphics.Drawing 651 * @since arkts {'1.1':'12','1.2':'20'} 652 * @arkts 1.1&1.2 653 */ 654 enum EllipsisMode { 655 /** 656 * Places the ellipsis in the text header. It is valid only when maxLines is set to 1 in ParagraphStyle. 657 * @syscap SystemCapability.Graphics.Drawing 658 * @since arkts {'1.1':'12','1.2':'20'} 659 * @arkts 1.1&1.2 660 */ 661 START, 662 663 /** 664 * Places the ellipsis in the middle of the text. It is valid only when maxLines is set to 1 in ParagraphStyle. 665 * @syscap SystemCapability.Graphics.Drawing 666 * @since arkts {'1.1':'12','1.2':'20'} 667 * @arkts 1.1&1.2 668 */ 669 MIDDLE, 670 671 /** 672 * Places the ellipsis at the end of the text. 673 * @syscap SystemCapability.Graphics.Drawing 674 * @since arkts {'1.1':'12','1.2':'20'} 675 * @arkts 1.1&1.2 676 */ 677 END, 678 } 679 680 /** 681 * Describes shadow of text. 682 * @typedef TextShadow 683 * @syscap SystemCapability.Graphics.Drawing 684 * @since arkts {'1.1':'12','1.2':'20'} 685 * @arkts 1.1&1.2 686 */ 687 interface TextShadow { 688 /** 689 * Color of the text shadow. The default value is black (255, 0, 0, 0). 690 * @type { ?common2D.Color } The color of text shadow 691 * @syscap SystemCapability.Graphics.Drawing 692 * @since arkts {'1.1':'12','1.2':'20'} 693 * @arkts 1.1&1.2 694 */ 695 color?: common2D.Color; 696 /** 697 * Position of the text shadow relative to the text. 698 * The horizontal and vertical coordinates must be greater than or equal to 0. 699 * @type { ?common2D.Point } The point of shadow 700 * @syscap SystemCapability.Graphics.Drawing 701 * @since arkts {'1.1':'12','1.2':'20'} 702 * @arkts 1.1&1.2 703 */ 704 point?: common2D.Point; 705 /** 706 * The value sets special effect radius of blurring text. 707 * The value is a floating point number. The default value is 0.0px. 708 * @type { ?number } The value about radius of blur, it type is "double" 709 * @syscap SystemCapability.Graphics.Drawing 710 * @since arkts {'1.1':'12','1.2':'20'} 711 * @arkts 1.1&1.2 712 */ 713 blurRadius?: number; 714 } 715 716 /** 717 * Describes the style of a rectangle. 718 * @typedef RectStyle 719 * @syscap SystemCapability.Graphics.Drawing 720 * @since arkts {'1.1':'12','1.2':'20'} 721 * @arkts 1.1&1.2 722 */ 723 interface RectStyle { 724 /** 725 * Color of the rectangle. 726 * @type { common2D.Color } The color of rect style 727 * @syscap SystemCapability.Graphics.Drawing 728 * @since arkts {'1.1':'12','1.2':'20'} 729 * @arkts 1.1&1.2 730 */ 731 color: common2D.Color; 732 733 /** 734 * Left top radius of the rectangle. 735 * @type { number } it is double type data 736 * @syscap SystemCapability.Graphics.Drawing 737 * @since arkts {'1.1':'12','1.2':'20'} 738 * @arkts 1.1&1.2 739 */ 740 leftTopRadius: number; 741 742 /** 743 * Right top radius of the rectangle. 744 * @type { number } it is double type data 745 * @syscap SystemCapability.Graphics.Drawing 746 * @since arkts {'1.1':'12','1.2':'20'} 747 * @arkts 1.1&1.2 748 */ 749 rightTopRadius: number; 750 751 /** 752 * Right bottom radius of the rectangle. 753 * @type { number } it is double type data 754 * @syscap SystemCapability.Graphics.Drawing 755 * @since arkts {'1.1':'12','1.2':'20'} 756 * @arkts 1.1&1.2 757 */ 758 rightBottomRadius: number; 759 760 /** 761 * Left bottom radius of the rectangle. 762 * @type { number } it is double type data 763 * @syscap SystemCapability.Graphics.Drawing 764 * @since arkts {'1.1':'12','1.2':'20'} 765 * @arkts 1.1&1.2 766 */ 767 leftBottomRadius: number; 768 } 769 770 /** 771 * Describes font feature of text. 772 * @typedef FontFeature 773 * @syscap SystemCapability.Graphics.Drawing 774 * @since arkts {'1.1':'12','1.2':'20'} 775 * @arkts 1.1&1.2 776 */ 777 interface FontFeature { 778 /** 779 * String identified by the keyword in the font feature key-value pair. 780 * @type { string } feature name 781 * @syscap SystemCapability.Graphics.Drawing 782 * @since arkts {'1.1':'12','1.2':'20'} 783 * @arkts 1.1&1.2 784 */ 785 name: string; 786 /** 787 * Value in the font feature key-value pair. 788 * @type { number } feature value 789 * @syscap SystemCapability.Graphics.Drawing 790 * @since arkts {'1.1':'12','1.2':'20'} 791 * @arkts 1.1&1.2 792 */ 793 value: number; 794 } 795 796 /** 797 * Describes font variation of text. 798 * @typedef FontVariation 799 * @syscap SystemCapability.Graphics.Drawing 800 * @since arkts {'1.1':'12','1.2':'20'} 801 * @arkts 1.1&1.2 802 */ 803 interface FontVariation { 804 /** 805 * String identified by the keyword in the font variation key-value pair. 806 * @type { string } variation axis 807 * @syscap SystemCapability.Graphics.Drawing 808 * @since arkts {'1.1':'12','1.2':'20'} 809 * @arkts 1.1&1.2 810 */ 811 axis: string; 812 /** 813 * Value in the font variation key-value pair. 814 * @type { number } variation value 815 * @syscap SystemCapability.Graphics.Drawing 816 * @since arkts {'1.1':'12','1.2':'20'} 817 * @arkts 1.1&1.2 818 */ 819 value: number; 820 } 821 822 /** 823 * Describes badge type of text. 824 * @enum { number } 825 * @syscap SystemCapability.Graphics.Drawing 826 * @since 20 827 */ 828 enum TextBadgeType { 829 /** 830 * No badge. 831 * @syscap SystemCapability.Graphics.Drawing 832 * @since 20 833 */ 834 TEXT_BADGE_NONE, 835 /** 836 * Superscript. 837 * @syscap SystemCapability.Graphics.Drawing 838 * @since 20 839 */ 840 TEXT_SUPERSCRIPT, 841 /** 842 * Subscript. 843 * @syscap SystemCapability.Graphics.Drawing 844 * @since 20 845 */ 846 TEXT_SUBSCRIPT, 847 } 848 849 /** 850 * Describes text style. 851 * @typedef TextStyle 852 * @syscap SystemCapability.Graphics.Drawing 853 * @since arkts {'1.1':'12','1.2':'20'} 854 * @arkts 1.1&1.2 855 */ 856 interface TextStyle { 857 858 /** 859 * Text decoration. By default, no decoration is used. 860 * @type { ?Decoration } decoration for text 861 * @syscap SystemCapability.Graphics.Drawing 862 * @since arkts {'1.1':'12','1.2':'20'} 863 * @arkts 1.1&1.2 864 */ 865 decoration?: Decoration; 866 867 /** 868 * Text color. The default color is white. 869 * @type { ?common2D.Color } it is uint32_t type data 870 * @syscap SystemCapability.Graphics.Drawing 871 * @since arkts {'1.1':'12','1.2':'20'} 872 * @arkts 1.1&1.2 873 */ 874 color?: common2D.Color; 875 876 /** 877 * Font weight. The default value is W400. Currently, only the default system font supports font weight adjustment. 878 * For other fonts, if the weight is less than semi-bold (W600), there is no variation in stroke thickness. 879 * If the weight is greater than or equal to semi-bold, it might result in a fake bold effect. 880 * @type { ?FontWeight } it is uint32_t type data 881 * @syscap SystemCapability.Graphics.Drawing 882 * @since arkts {'1.1':'12','1.2':'20'} 883 * @arkts 1.1&1.2 884 */ 885 fontWeight?: FontWeight; 886 887 /** 888 * Font style. The default value is NORMAL. 889 * @type { ?FontStyle } it is uint32_t type data 890 * @syscap SystemCapability.Graphics.Drawing 891 * @since arkts {'1.1':'12','1.2':'20'} 892 * @arkts 1.1&1.2 893 */ 894 fontStyle?: FontStyle; 895 896 /** 897 * Text baseline type. The default value is ALPHABETIC. 898 * @type { ?TextBaseline } it is uint32_t type data 899 * @syscap SystemCapability.Graphics.Drawing 900 * @since arkts {'1.1':'12','1.2':'20'} 901 * @arkts 1.1&1.2 902 */ 903 baseline?: TextBaseline; 904 905 /** 906 * Array of font families. By default, the array is empty, indicating that all system fonts are matched. 907 * @type { ?Array<string> } fontfamily gather 908 * @syscap SystemCapability.Graphics.Drawing 909 * @since arkts {'1.1':'12','1.2':'20'} 910 * @arkts 1.1&1.2 911 */ 912 fontFamilies?: Array<string>; 913 914 /** 915 * Font size, in units of px. The value is a floating point number. The default value is 14.0. 916 * @type { ?number } it is double type data 917 * @syscap SystemCapability.Graphics.Drawing 918 * @since arkts {'1.1':'12','1.2':'20'} 919 * @arkts 1.1&1.2 920 */ 921 fontSize?: number; 922 923 /** 924 * Letter spacing, in units of px. The value is a floating point number. 925 * The default value is 0.0. A positive value causes characters to spread farther apart, 926 * and a negative value bring characters closer together. 927 * @type { ?number } it is double type data 928 * @syscap SystemCapability.Graphics.Drawing 929 * @since arkts {'1.1':'12','1.2':'20'} 930 * @arkts 1.1&1.2 931 */ 932 letterSpacing?: number; 933 934 /** 935 * Word spacing, in units of px. The value is a floating point number. The default value is 0.0. 936 * @type { ?number } it is double type data 937 * @syscap SystemCapability.Graphics.Drawing 938 * @since arkts {'1.1':'12','1.2':'20'} 939 * @arkts 1.1&1.2 940 */ 941 wordSpacing?: number; 942 943 /** 944 * Scale factor of the line height. The value is a floating point number. 945 * The default value is 1.0. This parameter is valid only when heightOnly is set to true. 946 * @type { ?number } it is double type data 947 * @syscap SystemCapability.Graphics.Drawing 948 * @since arkts {'1.1':'12','1.2':'20'} 949 * @arkts 1.1&1.2 950 */ 951 heightScale?: number; 952 953 /** 954 * Whether half leading is enabled. 955 * Half leading is the leading split in half and applied equally to the top and bottom edges. 956 * The value true means that half leading is enabled, and false means the opposite. The default value is false. 957 * @type { ?boolean } it is boolean type data 958 * @syscap SystemCapability.Graphics.Drawing 959 * @since arkts {'1.1':'12','1.2':'20'} 960 * @arkts 1.1&1.2 961 */ 962 halfLeading?: boolean; 963 964 /** 965 * How the height of the text box is set. 966 * The value true means that the height of the text box is set based on the font size and the value of heightScale, 967 * and false means that the height is set based on the line height and line spacing. The default value is false. 968 * @type { ?boolean } it is boolean type data 969 * @syscap SystemCapability.Graphics.Drawing 970 * @since arkts {'1.1':'12','1.2':'20'} 971 * @arkts 1.1&1.2 972 */ 973 heightOnly?: boolean; 974 975 /** 976 * Ellipsis content, which will be used to replace the extra content. 977 * @type { ?string } it is u16string type data. 978 * @syscap SystemCapability.Graphics.Drawing 979 * @since arkts {'1.1':'12','1.2':'20'} 980 * @arkts 1.1&1.2 981 */ 982 ellipsis?: string; 983 984 /** 985 * Ellipsis type. The default value is END, indicating that the ellipsis is at the end of a line. 986 * @type { ?EllipsisMode } Ellipsis mode. 987 * @syscap SystemCapability.Graphics.Drawing 988 * @since arkts {'1.1':'12','1.2':'20'} 989 * @arkts 1.1&1.2 990 */ 991 ellipsisMode?: EllipsisMode; 992 993 /** 994 * Locale. For example, 'en' indicates English, 'zh-Hans' indicates Simplified Chinese, 995 * and 'zh-Hant' indicates Traditional Chinese. For details, see ISO 639-1. The default value is an empty string. 996 * @type { ?string } it is string type data. 997 * @syscap SystemCapability.Graphics.Drawing 998 * @since arkts {'1.1':'12','1.2':'20'} 999 * @arkts 1.1&1.2 1000 */ 1001 locale?: string; 1002 1003 /** 1004 * Shift of the baseline. The value is a floating point number. The default value is 0.0px. 1005 * @type { ?number } it is double type data. 1006 * @syscap SystemCapability.Graphics.Drawing 1007 * @since arkts {'1.1':'12','1.2':'20'} 1008 * @arkts 1.1&1.2 1009 */ 1010 baselineShift?: number; 1011 1012 /** 1013 * Text Style available font features. 1014 * @type { ?Array<FontFeature> } A collection of font features. 1015 * @syscap SystemCapability.Graphics.Drawing 1016 * @since arkts {'1.1':'12','1.2':'20'} 1017 * @arkts 1.1&1.2 1018 */ 1019 fontFeatures?: Array<FontFeature>; 1020 1021 /** 1022 * Text shadows of text. 1023 * @type { ?Array<TextShadow> } textShadow gather. 1024 * @syscap SystemCapability.Graphics.Drawing 1025 * @since arkts {'1.1':'12','1.2':'20'} 1026 * @arkts 1.1&1.2 1027 */ 1028 textShadows?: Array<TextShadow>; 1029 1030 /** 1031 * Rectangle style of text. 1032 * @type { ?RectStyle } rect style for text. 1033 * @syscap SystemCapability.Graphics.Drawing 1034 * @since arkts {'1.1':'12','1.2':'20'} 1035 * @arkts 1.1&1.2 1036 */ 1037 backgroundRect?: RectStyle; 1038 1039 /** 1040 * Text Style available font variations. 1041 * @type { ?Array<FontVariation> } A collection of font variations. 1042 * @syscap SystemCapability.Graphics.Drawing 1043 * @since arkts {'1.1':'12','1.2':'20'} 1044 * @arkts 1.1&1.2 1045 */ 1046 fontVariations?: Array<FontVariation>; 1047 1048 /** 1049 * Text style available badge type. 1050 * @type { ?TextBadgeType } The type of text badge type. 1051 * @syscap SystemCapability.Graphics.Drawing 1052 * @since 20 1053 */ 1054 badgeType?: TextBadgeType; 1055 } 1056 1057 /** 1058 * Implements a collection of fonts. 1059 * @syscap SystemCapability.Graphics.Drawing 1060 * @since arkts {'1.1':'12','1.2':'20'} 1061 * @arkts 1.1&1.2 1062 */ 1063 class FontCollection { 1064 /** 1065 * Get global FontCollection instance of the application. 1066 * @returns { FontCollection } The FontCollection object. 1067 * @syscap SystemCapability.Graphics.Drawing 1068 * @since arkts {'1.1':'12','1.2':'20'} 1069 * @arkts 1.1&1.2 1070 */ 1071 static getGlobalInstance(): FontCollection; 1072 1073 /** 1074 * Loads a custom font. This API returns the result synchronously. 1075 * In this API, name specifies the alias of the font, and the custom font effect can be displayed only when 1076 * the value of name is set in fontFamilies in TextStyle. The supported font file formats are .ttf and .otf. 1077 * @param { string } name - the font name. 1078 * @param { string | Resource } path - Path of the font file to import. The value must be 1079 * **file://**absolute path of the font file or **rawfile/**directory or file name. 1080 * @syscap SystemCapability.Graphics.Drawing 1081 * @since arkts {'1.1':'12','1.2':'20'} 1082 * @arkts 1.1&1.2 1083 */ 1084 loadFontSync(name: string, path: string | Resource): void; 1085 1086 /** 1087 * Loads a custom font. This API uses a promise to return the result. 1088 * In this API, name specifies the alias of the font, and the custom font effect can be displayed only when 1089 * the value of name is set in fontFamilies in TextStyle. The supported font file formats are ttf and otf. 1090 * @param { string } name - Name of the font. Any string is acceptable. 1091 * @param { string | Resource } path - Path of the font file to load. 1092 * The value must be **file://**absolute path of the font file or **rawfile/**directory or file name. 1093 * @returns { Promise<void> } Promise that returns no value. 1094 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 1095 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 1096 * @syscap SystemCapability.Graphics.Drawing 1097 * @since arkts {'1.1':'18','1.2':'20'} 1098 * @arkts 1.1&1.2 1099 */ 1100 loadFont(name: string, path: string | Resource): Promise<void>; 1101 1102 /** 1103 * Unloads a custom font synchronously. This API returns the result synchronously. 1104 * After unloading a font alias through this API, the corresponding custom font will no longer be available. 1105 * All typography using the font alias should be destroyed and re-created. 1106 * - Unloading a non-existent font alias has no effect and will **not** throw an error. 1107 * - This operation only affects subsequent font usages. 1108 * unload a font that is currently in used may lead to text rendering anomalies, 1109 * including garbled characters or missing glyphs. 1110 * @param { string } name - The alias of the font to unload. 1111 * This must exactly match the name used when loading the font through. 1112 * @syscap SystemCapability.Graphics.Drawing 1113 * @since 20 1114 */ 1115 unloadFontSync(name: string): void; 1116 1117 /** 1118 * Unloads a custom font. This API uses a promise to return the result. 1119 * After unloading a font alias through this API, the corresponding custom font will no longer be available. 1120 * All typography using the font alias should be destroyed and re-created. 1121 * - Unloading a non-existent font alias has no effect and will **not** throw an error. 1122 * - This operation only affects subsequent font usages. 1123 * unload a font that is currently in used may lead to text rendering anomalies, 1124 * including garbled characters or missing glyphs. 1125 * @param { string } name - The alias of the font to unload. 1126 * This must exactly match the name used when loading the font through. 1127 * @returns { Promise<void> } Promise that returns no value. 1128 * @syscap SystemCapability.Graphics.Drawing 1129 * @since 20 1130 */ 1131 unloadFont(name: string): Promise<void>; 1132 1133 /** 1134 * Clear font caches. 1135 * The font cache has a memory limit and a clearing mechanism. It occupies limited memory. 1136 * You are not advised to clear it unless otherwise required. 1137 * @syscap SystemCapability.Graphics.Drawing 1138 * @since arkts {'1.1':'12','1.2':'20'} 1139 * @arkts 1.1&1.2 1140 */ 1141 clearCaches(): void; 1142 } 1143 1144 /** 1145 * Describes the strut style, which determines the line spacing, baseline alignment mode, 1146 * and other properties related to the line height when drawing texts. The strut style is disabled by default. 1147 * @typedef StrutStyle 1148 * @syscap SystemCapability.Graphics.Drawing 1149 * @since arkts {'1.1':'12','1.2':'20'} 1150 * @arkts 1.1&1.2 1151 */ 1152 interface StrutStyle { 1153 /** 1154 * List of font families. By default, the list corresponds to the system's default fonts. 1155 * @type { ?Array<string> } fontfamily gather 1156 * @syscap SystemCapability.Graphics.Drawing 1157 * @since arkts {'1.1':'12','1.2':'20'} 1158 * @arkts 1.1&1.2 1159 */ 1160 fontFamilies?: Array<string>; 1161 1162 /** 1163 * Font style. The default value is NORMAL. 1164 * @type { ?FontStyle } it is uint32_t type data 1165 * @syscap SystemCapability.Graphics.Drawing 1166 * @since arkts {'1.1':'12','1.2':'20'} 1167 * @arkts 1.1&1.2 1168 */ 1169 fontStyle?: FontStyle; 1170 1171 /** 1172 * Font width. The default value is NORMAL. 1173 * @type { ?FontWidth } it is uint32_t type data 1174 * @syscap SystemCapability.Graphics.Drawing 1175 * @since arkts {'1.1':'12','1.2':'20'} 1176 * @arkts 1.1&1.2 1177 */ 1178 fontWidth?: FontWidth; 1179 1180 /** 1181 * Font weight. The default value is W400. The default system font supports font weight adjustment. 1182 * For other fonts, if the weight is less than W600, there is no variation in stroke thickness. 1183 * If the weight is greater than or equal to W600, it might result in a fake bold effect. 1184 * @type { ?FontWeight } it is uint32_t type data 1185 * @syscap SystemCapability.Graphics.Drawing 1186 * @since arkts {'1.1':'12','1.2':'20'} 1187 * @arkts 1.1&1.2 1188 */ 1189 fontWeight?: FontWeight; 1190 1191 /** 1192 * Font size, in units of px. The value is a floating point number. The default value is 14.0. 1193 * @type { ?number } it is double type data 1194 * @syscap SystemCapability.Graphics.Drawing 1195 * @since arkts {'1.1':'12','1.2':'20'} 1196 * @arkts 1.1&1.2 1197 */ 1198 fontSize?: number; 1199 1200 /** 1201 * Scale factor of the line height. The value is a floating point number. The default value is 1.0. 1202 * @type { ?number } it is double type data 1203 * @syscap SystemCapability.Graphics.Drawing 1204 * @since arkts {'1.1':'12','1.2':'20'} 1205 * @arkts 1.1&1.2 1206 */ 1207 height?: number; 1208 1209 /** 1210 * Custom leading to be applied to the strut. The value is a floating point number. The default value is -1.0. 1211 * @type { ?number } it is double type data 1212 * @syscap SystemCapability.Graphics.Drawing 1213 * @since arkts {'1.1':'12','1.2':'20'} 1214 * @arkts 1.1&1.2 1215 */ 1216 leading?: number; 1217 1218 /** 1219 * Whether to forcibly use the strut height for all lines. The value true means to forcibly use the strut height 1220 * for all lines, and false means the opposite. The default value is false. 1221 * @type { ?boolean } it is boolean type data 1222 * @syscap SystemCapability.Graphics.Drawing 1223 * @since arkts {'1.1':'12','1.2':'20'} 1224 * @arkts 1.1&1.2 1225 */ 1226 forceHeight?: boolean; 1227 1228 /** 1229 * Whether to enable the strut style. 1230 * The value true means to enable the strut style, and false means the opposite. The default value is false. 1231 * @type { ?boolean } it is boolean type data 1232 * @syscap SystemCapability.Graphics.Drawing 1233 * @since arkts {'1.1':'12','1.2':'20'} 1234 * @arkts 1.1&1.2 1235 */ 1236 enabled?: boolean; 1237 1238 /** 1239 * Whether to override the height. The value true means to override the height, and false means the opposite. 1240 * The default value is false. 1241 * @type { ?boolean } it is boolean type data 1242 * @syscap SystemCapability.Graphics.Drawing 1243 * @since arkts {'1.1':'12','1.2':'20'} 1244 * @arkts 1.1&1.2 1245 */ 1246 heightOverride?: boolean; 1247 1248 /** 1249 * Whether half leading is enabled. 1250 * Half leading is the leading split in half and applied equally to the top and bottom edges. 1251 * The value true means that half leading is enabled, and false means the opposite. The default value is false. 1252 * @type { ?boolean } it is boolean type data 1253 * @syscap SystemCapability.Graphics.Drawing 1254 * @since arkts {'1.1':'12','1.2':'20'} 1255 * @arkts 1.1&1.2 1256 */ 1257 halfLeading?: boolean; 1258 } 1259 1260 /** 1261 * Determines the configuration used by ParagraphBuilder to position lines within a Paragraph of text. 1262 * @typedef ParagraphStyle 1263 * @syscap SystemCapability.Graphics.Drawing 1264 * @since arkts {'1.1':'12','1.2':'20'} 1265 * @arkts 1.1&1.2 1266 */ 1267 interface ParagraphStyle { 1268 /** 1269 * Text style applied to the paragraph. The default value is the initial text style. 1270 * @type { ?TextStyle } 1271 * @syscap SystemCapability.Graphics.Drawing 1272 * @since arkts {'1.1':'12','1.2':'20'} 1273 * @arkts 1.1&1.2 1274 */ 1275 textStyle?: TextStyle; 1276 1277 /** 1278 * Text direction. The default value is LTR. 1279 * @type { ?TextDirection } 1280 * @syscap SystemCapability.Graphics.Drawing 1281 * @since arkts {'1.1':'12','1.2':'20'} 1282 * @arkts 1.1&1.2 1283 */ 1284 textDirection?: TextDirection; 1285 1286 /** 1287 * Text alignment mode. The default value is START. This parameter is invalid when the tab parameter is configured. 1288 * @type { ?TextAlign } 1289 * @syscap SystemCapability.Graphics.Drawing 1290 * @since arkts {'1.1':'12','1.2':'20'} 1291 * @arkts 1.1&1.2 1292 */ 1293 align?: TextAlign; 1294 1295 /** 1296 * Word break type. The default value is BREAK_WORD. 1297 * @type { ?WordBreak } 1298 * @syscap SystemCapability.Graphics.Drawing 1299 * @since arkts {'1.1':'12','1.2':'20'} 1300 * @arkts 1.1&1.2 1301 */ 1302 wordBreak?: WordBreak; 1303 1304 /** 1305 * Maximum number of lines. The value is an integer. The default value is 1e9. 1306 * @type { ?number } 1307 * @syscap SystemCapability.Graphics.Drawing 1308 * @since arkts {'1.1':'12','1.2':'20'} 1309 * @arkts 1.1&1.2 1310 */ 1311 maxLines?: number; 1312 1313 /** 1314 * Text break strategy. The default value is GREEDY. 1315 * @type { ?BreakStrategy } 1316 * @syscap SystemCapability.Graphics.Drawing 1317 * @since arkts {'1.1':'12','1.2':'20'} 1318 * @arkts 1.1&1.2 1319 */ 1320 breakStrategy?: BreakStrategy; 1321 1322 /** 1323 * Strut style. The default value is the initial StrutStyle object. 1324 * @type { ?StrutStyle } 1325 * @syscap SystemCapability.Graphics.Drawing 1326 * @since arkts {'1.1':'12','1.2':'20'} 1327 * @arkts 1.1&1.2 1328 */ 1329 strutStyle?: StrutStyle; 1330 1331 /** 1332 * Text height modifier pattern. The default value is ALL. 1333 * @type { ?TextHeightBehavior } 1334 * @syscap SystemCapability.Graphics.Drawing 1335 * @since arkts {'1.1':'12','1.2':'20'} 1336 * @arkts 1.1&1.2 1337 */ 1338 textHeightBehavior?: TextHeightBehavior; 1339 1340 /** 1341 * Alignment mode and position of the text after the tab character in a paragraph. By default, the tab character 1342 * is replaced with a space. This parameter is invalid when it is used together with the align parameter or 1343 * the ellipsis parameter in TextStyle. 1344 * @type { ?TextTab } 1345 * @syscap SystemCapability.Graphics.Drawing 1346 * @since arkts {'1.1':'18','1.2':'20'} 1347 * @arkts 1.1&1.2 1348 */ 1349 tab?: TextTab; 1350 1351 /** 1352 * Whether to optimize white spaces at the end of each line. 1353 * @type { ?boolean } Boolean type data. 1354 * @syscap SystemCapability.Graphics.Drawing 1355 * @since 20 1356 */ 1357 trailingSpaceOptimized?: boolean; 1358 1359 /** 1360 * Whether to enable automatic spacing between Chinese and English for paragraph. 1361 * @type { ?boolean } 1362 * @syscap SystemCapability.Graphics.Drawing 1363 * @since 20 1364 */ 1365 autoSpace?: boolean; 1366 1367 /** 1368 * Vertical alignment mode of the paragraph. 1369 * @type { ?TextVerticalAlign } 1370 * @syscap SystemCapability.Graphics.Drawing 1371 * @since 20 1372 */ 1373 verticalAlign?: TextVerticalAlign; 1374 } 1375 1376 /** 1377 * Enumerates the vertical alignment modes of a placeholder relative to the surrounding text. 1378 * @enum { number } 1379 * @syscap SystemCapability.Graphics.Drawing 1380 * @since 12 1381 */ 1382 enum PlaceholderAlignment { 1383 /** 1384 * Aligns the baseline of the placeholder to the baseline of the text. 1385 * @syscap SystemCapability.Graphics.Drawing 1386 * @since 12 1387 */ 1388 OFFSET_AT_BASELINE, 1389 1390 /** 1391 * Aligns the bottom edge of the placeholder to the baseline of the text. 1392 * sits on top of the baseline. 1393 * @syscap SystemCapability.Graphics.Drawing 1394 * @since 12 1395 */ 1396 ABOVE_BASELINE, 1397 1398 /** 1399 * Aligns the top edge of the placeholder to the baseline of the text. 1400 * hangs below the baseline. 1401 * @syscap SystemCapability.Graphics.Drawing 1402 * @since 12 1403 */ 1404 BELOW_BASELINE, 1405 1406 /** 1407 * Align the top edge of the placeholder with the top edge of the font. When the placeholder is very tall, 1408 * the extra space will hang from the top and extend through the bottom of the line. 1409 * @syscap SystemCapability.Graphics.Drawing 1410 * @since 12 1411 */ 1412 TOP_OF_ROW_BOX, 1413 1414 /** 1415 * Align the bottom edge of the placeholder with the bottom edge of the text. When the placeholder is very tall, 1416 * the extra space will rise from the bottom and extend through the top of the line. 1417 * @syscap SystemCapability.Graphics.Drawing 1418 * @since 12 1419 */ 1420 BOTTOM_OF_ROW_BOX, 1421 1422 /** 1423 * Align the middle of the placeholder with the middle of the text. When the placeholder is very tall, 1424 * the extra space will grow equally from the top and bottom of the line. 1425 * @syscap SystemCapability.Graphics.Drawing 1426 * @since 12 1427 */ 1428 CENTER_OF_ROW_BOX, 1429 1430 /** 1431 * Follow Paragraph setting, 1432 * @syscap SystemCapability.Graphics.Drawing 1433 * @since 20 1434 */ 1435 FOLLOW_PARAGRAPH, 1436 } 1437 1438 /** 1439 * Describes the placeholder style. 1440 * @typedef PlaceholderSpan 1441 * @syscap SystemCapability.Graphics.Drawing 1442 * @since 12 1443 */ 1444 interface PlaceholderSpan { 1445 /** 1446 * Width of the placeholder, in units of px. The value is a floating point number. 1447 * @type { number } 1448 * @syscap SystemCapability.Graphics.Drawing 1449 * @since 12 1450 */ 1451 width: number; 1452 1453 /** 1454 * Height of the placeholder, in units of px. The value is a floating point number. 1455 * @type { number } 1456 * @syscap SystemCapability.Graphics.Drawing 1457 * @since 12 1458 */ 1459 height: number; 1460 1461 /** 1462 * Vertical alignment of the placeholder relative to the surrounding text. 1463 * @type { PlaceholderAlignment } 1464 * @syscap SystemCapability.Graphics.Drawing 1465 * @since 12 1466 */ 1467 align: PlaceholderAlignment; 1468 1469 /** 1470 * Type of the text baseline. 1471 * @type { TextBaseline } 1472 * @syscap SystemCapability.Graphics.Drawing 1473 * @since 12 1474 */ 1475 baseline: TextBaseline; 1476 1477 /** 1478 * Offset to the text baseline, in units of px. The value is a floating point number. 1479 * @type { number } 1480 * @syscap SystemCapability.Graphics.Drawing 1481 * @since 12 1482 */ 1483 baselineOffset: number; 1484 } 1485 1486 /** 1487 * Describes a left-closed and right-open interval. 1488 * @typedef Range 1489 * @syscap SystemCapability.Graphics.Drawing 1490 * @since 12 1491 */ 1492 interface Range { 1493 /** 1494 * Index of the leftmost point of the interval. The value is an integer. 1495 * @type { number } 1496 * @syscap SystemCapability.Graphics.Drawing 1497 * @since 12 1498 */ 1499 start: number; 1500 1501 /** 1502 * Index of the rightmost point of the interval. The value is an integer. 1503 * @type { number } 1504 * @syscap SystemCapability.Graphics.Drawing 1505 * @since 12 1506 */ 1507 end: number; 1508 } 1509 1510 /** 1511 * Enumerates the font types, which can be combined through bitwise OR operations. 1512 * @enum { number } 1513 * @syscap SystemCapability.Graphics.Drawing 1514 * @since 14 1515 */ 1516 enum SystemFontType { 1517 /** 1518 * All font types, including the system font type, style font type, and user-installed font type. 1519 * @syscap SystemCapability.Graphics.Drawing 1520 * @since 14 1521 */ 1522 ALL = 1 << 0, 1523 1524 /** 1525 * System generic font type. 1526 * @syscap SystemCapability.Graphics.Drawing 1527 * @since 14 1528 */ 1529 GENERIC = 1 << 1, 1530 1531 /** 1532 * Style font type. The style font type is designed for 2-in-1 devices. 1533 * @syscap SystemCapability.Graphics.Drawing 1534 * @since 14 1535 */ 1536 STYLISH = 1 << 2, 1537 1538 /** 1539 * Font type that has been installed. 1540 * @syscap SystemCapability.Graphics.Drawing 1541 * @since 14 1542 */ 1543 INSTALLED = 1 << 3, 1544 1545 /** 1546 * Customized font types. 1547 * @syscap SystemCapability.Graphics.Drawing 1548 * @since 18 1549 */ 1550 CUSTOMIZED = 1 << 4, 1551 } 1552 1553 /** 1554 * Describes the font descriptor information. 1555 * @typedef FontDescriptor 1556 * @syscap SystemCapability.Graphics.Drawing 1557 * @since 14 1558 */ 1559 interface FontDescriptor { 1560 /** 1561 * Absolute path of the font. Any string is acceptable, but the value must adhere to the system's path constraints. 1562 * The default value is an empty string. 1563 * @type { ?string } 1564 * @syscap SystemCapability.Graphics.Drawing 1565 * @since 14 1566 */ 1567 path?: string; 1568 1569 /** 1570 * Unique name of the font. Any string is acceptable. The default value is an empty string. 1571 * @type { ?string } 1572 * @syscap SystemCapability.Graphics.Drawing 1573 * @since 14 1574 */ 1575 postScriptName?: string; 1576 1577 /** 1578 * Font name. Any string is acceptable. The default value is an empty string. 1579 * @type { ?string } 1580 * @syscap SystemCapability.Graphics.Drawing 1581 * @since 14 1582 */ 1583 fullName?: string; 1584 1585 /** 1586 * Family name of the font. Any string is acceptable. The default value is an empty string. 1587 * @type { ?string } 1588 * @syscap SystemCapability.Graphics.Drawing 1589 * @since 14 1590 */ 1591 fontFamily?: string; 1592 1593 /** 1594 * Subfamily name of the font. Any string is acceptable. The default value is an empty string. 1595 * @type { ?string } 1596 * @syscap SystemCapability.Graphics.Drawing 1597 * @since 14 1598 */ 1599 fontSubfamily?: string; 1600 1601 /** 1602 * Font weight. The default value is 0. 1603 * @type { ?FontWeight } 1604 * @syscap SystemCapability.Graphics.Drawing 1605 * @since 14 1606 */ 1607 weight?: FontWeight; 1608 1609 /** 1610 * Font width. The value is an integer ranging from 1 to 9. The default value is 0. 1611 * @type { ?number } 1612 * @syscap SystemCapability.Graphics.Drawing 1613 * @since 14 1614 */ 1615 width?: number; 1616 1617 /** 1618 * Whether the font is italic. The value 0 means that the font is not italic, and 1 means the opposite. 1619 * The default value is 0. 1620 * @type { ?number } 1621 * @syscap SystemCapability.Graphics.Drawing 1622 * @since 14 1623 */ 1624 italic?: number; 1625 1626 /** 1627 * Whether the font is monospaced. The value true means that the font is monospaced, and false means the opposite. 1628 * The default value is false. 1629 * @type { ?boolean } 1630 * @syscap SystemCapability.Graphics.Drawing 1631 * @since 14 1632 */ 1633 monoSpace?: boolean; 1634 1635 /** 1636 * Whether the font is symbolic. The value true means that the font is symbolic, and false means the opposite. 1637 * @type { ?boolean } 1638 * @syscap SystemCapability.Graphics.Drawing 1639 * @since 14 1640 */ 1641 symbolic?: boolean; 1642 } 1643 1644 /** 1645 * Implements a carrier that stores the text content and style. You can perform operations such as layout and drawing. 1646 * Before calling any of the following APIs, you must use build() of the ParagraphBuilder class to 1647 * create a Paragraph object. 1648 * @syscap SystemCapability.Graphics.Drawing 1649 * @since arkts {'1.1':'12','1.2':'20'} 1650 * @arkts 1.1&1.2 1651 */ 1652 class Paragraph { 1653 /** 1654 * Performs layout and calculates the positions of all glyphs. 1655 * @param { number } width - Maximum width of a single line, in units of px. The value is a floating point number. 1656 * @syscap SystemCapability.Graphics.Drawing 1657 * @since arkts {'1.1':'12','1.2':'20'} 1658 * @arkts 1.1&1.2 1659 */ 1660 layoutSync(width: number): void; 1661 1662 /** 1663 * Performs layout and calculates the positions of all glyphs. This API uses a promise to return the result. 1664 * @param { number } width - Maximum width of a single line, in units of px. The value is a floating point number. 1665 * @returns { Promise<void> } Promise that returns no value. 1666 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 1667 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 1668 * @syscap SystemCapability.Graphics.Drawing 1669 * @since 18 1670 */ 1671 layout(width: number): Promise<void>; 1672 1673 /** 1674 * Paints the text on the canvas with the coordinate point (x, y) as the upper left corner. 1675 * @param { drawing.Canvas } canvas - Target canvas. 1676 * @param { number } x - X coordinate of the upper left corner. The value is a floating point number. 1677 * @param { number } y - Y coordinate of the upper left corner. The value is a floating point number. 1678 * @syscap SystemCapability.Graphics.Drawing 1679 * @since arkts {'1.1':'12','1.2':'20'} 1680 * @arkts 1.1&1.2 1681 */ 1682 paint(canvas: drawing.Canvas, x: number, y: number): void; 1683 1684 /** 1685 * Draw the laid out text onto the supplied canvas along the path and offset. 1686 * @param { drawing.Canvas } canvas - Canvas used to carry the drawn content and drawing status. 1687 * @param { drawing.Path } path - Path used to determine the position of the text. 1688 * @param { number } hOffset - Horizontal offset along the path direction. A positive number indicates a position 1689 * that is ahead along the path from its start point, and a negative number indicates a position that is behind 1690 * from the start point. 1691 * @param { number } vOffset - Vertical offset along the path direction. A positive number indicates a position 1692 * on the left side of the path, and a negative number indicates a position on the right side of the path. 1693 * @syscap SystemCapability.Graphics.Drawing 1694 * @since arkts {'1.1':'12','1.2':'20'} 1695 * @arkts 1.1&1.2 1696 */ 1697 paintOnPath(canvas: drawing.Canvas, path: drawing.Path, hOffset: number, vOffset: number): void; 1698 1699 /** 1700 * Obtains the maximum width of the line in the text. 1701 * @returns { number } Maximum line width, in units of px. The value is a floating point number. 1702 * @syscap SystemCapability.Graphics.Drawing 1703 * @since 12 1704 */ 1705 getMaxWidth(): number; 1706 1707 /** 1708 * Obtains the total height of the text. 1709 * @returns { number } Total height, in units of px. The value is a floating point number. 1710 * @syscap SystemCapability.Graphics.Drawing 1711 * @since 12 1712 */ 1713 getHeight(): number; 1714 1715 /** 1716 * Obtains the longest line in the text. 1717 * @returns { number } Longest line, in units of px. The value is a floating point number. 1718 * @syscap SystemCapability.Graphics.Drawing 1719 * @since arkts {'1.1':'12','1.2':'20'} 1720 * @arkts 1.1&1.2 1721 */ 1722 getLongestLine(): number; 1723 1724 /** 1725 * Obtains the width of the longest line, including its indentation, in the text. 1726 * You are advised to round up the return value. If the text content is empty, 0 is returned. 1727 * @returns { number } Width of the longest line, including its indentation. 1728 * The value is a floating point number, in px. 1729 * @syscap SystemCapability.Graphics.Drawing 1730 * @since 13 1731 */ 1732 getLongestLineWithIndent(): number; 1733 1734 /** 1735 * Obtains the minimum intrinsic width of the paragraph. 1736 * @returns { number } Minimum intrinsic width, in units of px. The value is a floating point number. 1737 * @syscap SystemCapability.Graphics.Drawing 1738 * @since 12 1739 */ 1740 getMinIntrinsicWidth(): number; 1741 1742 /** 1743 * Obtains the maximum intrinsic width of the paragraph. 1744 * @returns { number } Maximum intrinsic width, in units of px. The value is a floating point number. 1745 * @syscap SystemCapability.Graphics.Drawing 1746 * @since 12 1747 */ 1748 getMaxIntrinsicWidth(): number; 1749 1750 /** 1751 * Obtains the alphabetic baseline. 1752 * @returns { number } Alphabetic baseline, in units of px. The value is a floating point number. 1753 * @syscap SystemCapability.Graphics.Drawing 1754 * @since 12 1755 */ 1756 getAlphabeticBaseline(): number; 1757 1758 /** 1759 * Obtains the ideographic baseline. 1760 * @returns { number } Ideographic baseline, in units of px. The value is a floating point number. 1761 * @syscap SystemCapability.Graphics.Drawing 1762 * @since 12 1763 */ 1764 getIdeographicBaseline(): number; 1765 1766 /** 1767 * Obtains the rectangles occupied by the characters in the range of the text under the given rectangle width and 1768 * height. 1769 * @param { Range } range - Range of the text. 1770 * @param { RectWidthStyle } widthStyle - Width of the rectangle. 1771 * @param { RectHeightStyle } heightStyle - Height of the rectangle. 1772 * @returns { Array<TextBox> } Array holding the rectangles obtained. 1773 * @syscap SystemCapability.Graphics.Drawing 1774 * @since 12 1775 */ 1776 getRectsForRange(range: Range, widthStyle: RectWidthStyle, heightStyle: RectHeightStyle): Array<TextBox>; 1777 1778 /** 1779 * Obtains the rectangles occupied by all placeholders in the text. 1780 * @returns { Array<TextBox> } Array holding the rectangles obtained. 1781 * @syscap SystemCapability.Graphics.Drawing 1782 * @since 12 1783 */ 1784 getRectsForPlaceholders(): Array<TextBox>; 1785 1786 /** 1787 * Obtains the position of a glyph closest to the given coordinates. 1788 * @param { number } x - X coordinate. The value is a floating point number. 1789 * @param { number } y - Y coordinate. The value is a floating point number. 1790 * @returns { PositionWithAffinity } Position of the glyph. 1791 * @syscap SystemCapability.Graphics.Drawing 1792 * @since 12 1793 */ 1794 getGlyphPositionAtCoordinate(x: number, y: number): PositionWithAffinity; 1795 1796 /** 1797 * Obtains the range of the word where the glyph with a given offset is located. 1798 * @param { number } offset - Offset of the glyph. The value is an integer. 1799 * @returns { Range } Range of the word. 1800 * @syscap SystemCapability.Graphics.Drawing 1801 * @since 12 1802 */ 1803 getWordBoundary(offset: number): Range; 1804 1805 /** 1806 * Obtains the number of text lines. 1807 * @returns { number } Number of text lines. The value is an integer. 1808 * @syscap SystemCapability.Graphics.Drawing 1809 * @since 12 1810 */ 1811 getLineCount(): number; 1812 1813 /** 1814 * Obtains the height of a given line. 1815 * @param { number } line - Index of the line. The value is an integer ranging from 0 to getLineCount() – 1. 1816 * @returns { number } The line height value returned to the caller. 1817 * @syscap SystemCapability.Graphics.Drawing 1818 * @since 12 1819 */ 1820 getLineHeight(line: number): number; 1821 1822 /** 1823 * Obtains the width of a given line. 1824 * @param { number } line - Index of the line. The value is an integer ranging from 0 to getLineCount() – 1. 1825 * @returns { number } The line width value returned to the caller. 1826 * @syscap SystemCapability.Graphics.Drawing 1827 * @since 12 1828 */ 1829 getLineWidth(line: number): number; 1830 1831 /** 1832 * Checks whether the number of lines in the paragraph exceeds the maximum. 1833 * @returns { boolean } Check result. The value true means that the number of lines exceeds the maximum, 1834 * and false means the opposite. 1835 * @syscap SystemCapability.Graphics.Drawing 1836 * @since 12 1837 */ 1838 didExceedMaxLines(): boolean; 1839 1840 /** 1841 * Obtains all the text lines. 1842 * @returns { Array<TextLine> } Array of text lines. 1843 * @syscap SystemCapability.Graphics.Drawing 1844 * @since 12 1845 */ 1846 getTextLines(): Array<TextLine>; 1847 1848 /** 1849 * Obtains the actually visible text range in the specified line, excluding any overflow ellipsis. 1850 * @param { number } lineNumber - Line number of the text range, starting from 0. This API can only be used to 1851 * obtain the bounds of existing lines. That is, the line number must start from 0, and the maximum line number 1852 * is getLineCount - 1. 1853 * @param { boolean } includeSpaces - Whether spaces are included. The value true means that spaces are contained, 1854 * and false means the opposite. 1855 * @returns { Range } Text range obtained. If the line index is invalid, start and end are both 0. 1856 * @syscap SystemCapability.Graphics.Drawing 1857 * @since 12 1858 */ 1859 getActualTextRange(lineNumber: number, includeSpaces: boolean): Range; 1860 1861 /** 1862 * Obtains an array of line measurement information. 1863 * @returns { Array<LineMetrics> } Array of line measurement information. 1864 * @syscap SystemCapability.Graphics.Drawing 1865 * @since arkts {'1.1':'12','1.2':'20'} 1866 * @arkts 1.1&1.2 1867 */ 1868 getLineMetrics(): Array<LineMetrics>; 1869 1870 /** 1871 * Obtains the line measurement information of a line. 1872 * @param { number } lineNumber - Line number, starting from 0. 1873 * @returns { LineMetrics | undefined } LineMetrics object containing the measurement information if the specified 1874 * line number is valid and the measurement information exists. If the line number is invalid or 1875 * the measurement information cannot be obtained, undefined is returned. 1876 * @syscap SystemCapability.Graphics.Drawing 1877 * @since arkts {'1.1':'12','1.2':'20'} 1878 * @arkts 1.1&1.2 1879 */ 1880 getLineMetrics(lineNumber: number): LineMetrics | undefined; 1881 1882 /** 1883 * Synchronously updates the text color of the typography. 1884 * @param { common2D.Color } color - Color of text. 1885 * @syscap SystemCapability.Graphics.Drawing 1886 * @since 20 1887 */ 1888 updateColor(color: common2D.Color): void; 1889 1890 /** 1891 * Synchronously updates text decoration. 1892 * @param { Decoration } decoration - Decoration of text. 1893 * @syscap SystemCapability.Graphics.Drawing 1894 * @since 20 1895 */ 1896 updateDecoration(decoration: Decoration): void; 1897 } 1898 1899 /** 1900 * Implements a carrier that stores the text content and style. It can be used to compute layout details for 1901 * individual lines of text. Before calling any of the following APIs, you must use buildLineTypeset() 1902 * in the ParagraphBuilder class to create a LineTypeset object. 1903 * @syscap SystemCapability.Graphics.Drawing 1904 * @since 18 1905 */ 1906 class LineTypeset { 1907 /** 1908 * Obtains the number of characters that can fit in the layout from the specified position within a limited width. 1909 * @param { number } startIndex - Start position (inclusive) for calculation. The value is an integer in the range 1910 * [0, total number of text characters). If the parameter is invalid, an exception is thrown. 1911 * @param { number } width - Layout width. The value is a floating point number greater than 0, in px. 1912 * @returns { number } Number of characters. 1913 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 1914 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 1915 * @syscap SystemCapability.Graphics.Drawing 1916 * @since 18 1917 */ 1918 getLineBreak(startIndex: number, width: number): number; 1919 1920 /** 1921 * Generates a text line object based on the specified layout range. 1922 * @param { number } startIndex - Start position for layout calculation. The value is an integer in the 1923 * range [0, total number of text characters). 1924 * @param { number } count - Number of characters from the specified start position. The value is an integer in 1925 * the range [0, total number of text characters). The sum of startIndex and count cannot be greater than 1926 * the total number of text characters. When count is 0, the range is [startIndex, end of the text]. 1927 * You can use getLineBreak to obtain the number of characters that can fit in the layout. 1928 * @returns { TextLine } TextLine object generated based on the characters in the text range. 1929 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 1930 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 1931 * @syscap SystemCapability.Graphics.Drawing 1932 * @since 18 1933 */ 1934 createLine(startIndex: number, count: number): TextLine; 1935 } 1936 1937 /** 1938 * Describes the rectangle that holds the text. 1939 * @typedef TextBox 1940 * @syscap SystemCapability.Graphics.Drawing 1941 * @since 12 1942 */ 1943 interface TextBox{ 1944 /** 1945 * Information about the rectangle. 1946 * @type { common2D.Rect } 1947 * @syscap SystemCapability.Graphics.Drawing 1948 * @since 12 1949 */ 1950 rect: common2D.Rect; 1951 1952 /** 1953 * Text direction. 1954 * @type { TextDirection } 1955 * @syscap SystemCapability.Graphics.Drawing 1956 * @since 12 1957 */ 1958 direction: TextDirection; 1959 } 1960 1961 /** 1962 * Describes the position and affinity of a glyph. 1963 * @typedef PositionWithAffinity 1964 * @syscap SystemCapability.Graphics.Drawing 1965 * @since 12 1966 */ 1967 interface PositionWithAffinity { 1968 /** 1969 * Index of the glyph relative to the paragraph. The value is an integer. 1970 * @type { number } 1971 * @syscap SystemCapability.Graphics.Drawing 1972 * @since 12 1973 */ 1974 position: number; 1975 1976 /** 1977 * Affinity of the position. 1978 * @type { Affinity } 1979 * @syscap SystemCapability.Graphics.Drawing 1980 * @since 12 1981 */ 1982 affinity: Affinity; 1983 } 1984 1985 /** 1986 * Enumerates the rectangle width styles. 1987 * @enum { number } 1988 * @syscap SystemCapability.Graphics.Drawing 1989 * @since 12 1990 */ 1991 enum RectWidthStyle { 1992 /** 1993 * If letterSpacing is not set, the rectangle conforms tightly to the text it contains. 1994 * However, if letterSpacing is set, a gap is introduced between the rectangle and text. 1995 * @syscap SystemCapability.Graphics.Drawing 1996 * @since 12 1997 */ 1998 TIGHT, 1999 2000 /** 2001 * The rectangle's width is extended to align with the widest rectangle across all lines. 2002 * @syscap SystemCapability.Graphics.Drawing 2003 * @since 12 2004 */ 2005 MAX, 2006 } 2007 2008 /** 2009 * Enumerates the rectangle height styles. 2010 * @enum { number } 2011 * @syscap SystemCapability.Graphics.Drawing 2012 * @since 12 2013 */ 2014 enum RectHeightStyle { 2015 /** 2016 * Tight style. 2017 * @syscap SystemCapability.Graphics.Drawing 2018 * @since 12 2019 */ 2020 TIGHT, 2021 2022 /** 2023 * Extends the height to match the highest rectangle in all lines. 2024 * @syscap SystemCapability.Graphics.Drawing 2025 * @since 12 2026 */ 2027 MAX, 2028 2029 /** 2030 * The top and bottom of each rect will cover half of the space above and half of the space below the line. 2031 * @syscap SystemCapability.Graphics.Drawing 2032 * @since 12 2033 */ 2034 INCLUDE_LINE_SPACE_MIDDLE, 2035 2036 /** 2037 * The line spacing will be added to the top of the rect. 2038 * @syscap SystemCapability.Graphics.Drawing 2039 * @since 12 2040 */ 2041 INCLUDE_LINE_SPACE_TOP, 2042 2043 /** 2044 * The line spacing will be added to the bottom of the rect. 2045 * @syscap SystemCapability.Graphics.Drawing 2046 * @since 12 2047 */ 2048 INCLUDE_LINE_SPACE_BOTTOM, 2049 2050 /** 2051 * The height of the boxes will be calculated by text strut. 2052 * @syscap SystemCapability.Graphics.Drawing 2053 * @since 12 2054 */ 2055 STRUT, 2056 } 2057 2058 /** 2059 * Enumerates text affinity.When a selection range involves line breaks or other special characters, the 2060 * affinity determines which side of the characters the start and end of the selection range should be 2061 * closer to. 2062 * @enum { number } 2063 * @syscap SystemCapability.Graphics.Drawing 2064 * @since 12 2065 */ 2066 enum Affinity { 2067 /** 2068 * The position has affinity for the upstream side of the text position. 2069 * @syscap SystemCapability.Graphics.Drawing 2070 * @since 12 2071 */ 2072 2073 UPSTREAM, 2074 /** 2075 * The position has affinity for the downstream side of the text position. 2076 * @syscap SystemCapability.Graphics.Drawing 2077 * @since 12 2078 */ 2079 DOWNSTREAM, 2080 } 2081 2082 /** 2083 * Builds a Paragraph containing text with the given styling information. 2084 * @syscap SystemCapability.Graphics.Drawing 2085 * @since arkts {'1.1':'12','1.2':'20'} 2086 * @arkts 1.1&1.2 2087 */ 2088 class ParagraphBuilder { 2089 /** 2090 * A constructor used to create a ParagraphBuilder object. 2091 * @param { ParagraphStyle } paragraphStyle - Paragraph style {@link ParagraphStyle} 2092 * @param { FontCollection } fontCollection - Font collection {@link FontCollection} 2093 * @syscap SystemCapability.Graphics.Drawing 2094 * @since arkts {'1.1':'12','1.2':'20'} 2095 * @arkts 1.1&1.2 2096 */ 2097 constructor(paragraphStyle: ParagraphStyle, fontCollection: FontCollection); 2098 2099 /** 2100 * Applies a new style to the current text blob. 2101 * <p>**NOTE**</p> 2102 * When you update the style of the current text blob, all text added afterward will use this new style. 2103 * @param { TextStyle } textStyle - Text style, which describes various visual attributes of text, such as font, 2104 * font size, color, font weight, word spacing, line spacing, decoration (such as underline and strikethrough), 2105 * and text shadow. {@link TextStyle} 2106 * @syscap SystemCapability.Graphics.Drawing 2107 * @since arkts {'1.1':'12','1.2':'20'} 2108 * @arkts 1.1&1.2 2109 */ 2110 pushStyle(textStyle: TextStyle): void; 2111 2112 /** 2113 * Restores the previous text style. 2114 * @syscap SystemCapability.Graphics.Drawing 2115 * @since arkts {'1.1':'12','1.2':'20'} 2116 * @arkts 1.1&1.2 2117 */ 2118 popStyle(): void; 2119 2120 /** 2121 * Inserts a text string into the paragraph being built. 2122 * @param { string } text - Exact text string inserted into the paragraph. If an invalid Unicode character is 2123 * provided, it is displayed as �. 2124 * @syscap SystemCapability.Graphics.Drawing 2125 * @since arkts {'1.1':'12','1.2':'20'} 2126 * @arkts 1.1&1.2 2127 */ 2128 addText(text: string): void; 2129 2130 /** 2131 * Inserts a placeholder into the paragraph being built. 2132 * @param { PlaceholderSpan } placeholderSpan - Placeholder span, which describes the size, alignment, 2133 * baseline type, and baseline offset of the placeholder. {@link PlaceholderSpan} 2134 * @syscap SystemCapability.Graphics.Drawing 2135 * @since 12 2136 */ 2137 addPlaceholder(placeholderSpan: PlaceholderSpan): void; 2138 2139 /** 2140 * Creates a paragraph object that can be used for subsequent layout and rendering. 2141 * @returns { Paragraph } Paragraph object that can be used for subsequent rendering. 2142 * @syscap SystemCapability.Graphics.Drawing 2143 * @since arkts {'1.1':'12','1.2':'20'} 2144 * @arkts 1.1&1.2 2145 */ 2146 build(): Paragraph; 2147 2148 /** 2149 * Builds a line typesetter. 2150 * @returns { LineTypeset } LineTypeset object that can be used for subsequent rendering. 2151 * @syscap SystemCapability.Graphics.Drawing 2152 * @since 18 2153 */ 2154 buildLineTypeset(): LineTypeset; 2155 2156 /** 2157 * Inserts a symbol into the paragraph being built. 2158 * @param { number } symbolId - Symbol code to insert. The value is a hexadecimal number in the 2159 * range 0xF0000-0xF0C97. For details about the configurable symbol codes (unicode values in the list view), 2160 * see <a href="https://developer.huawei.com/consumer/cn/design/harmonyos-symbol/">HarmonyOS Symbol</a>. 2161 * @syscap SystemCapability.Graphics.Drawing 2162 * @since 12 2163 */ 2164 addSymbol(symbolId: number): void; 2165 } 2166 2167 /** 2168 * Describes the typographic boundaries of a text line. These boundaries depend on the typographic font and font size, 2169 * not on the characters themselves. For example, for the string " a b " (which has a space before "a" and a space 2170 * after "b"), the typographic boundaries include the spaces at the beginning and end of the line. Similarly, 2171 * the strings "j" and "E" have identical typographic boundaries, which are independent of the characters themselves. 2172 * @typedef TypographicBounds 2173 * @syscap SystemCapability.Graphics.Drawing 2174 * @since 18 2175 */ 2176 interface TypographicBounds { 2177 /** 2178 * Ascent of a text line. The value is a floating point number. 2179 * @type { number } 2180 * @syscap SystemCapability.Graphics.Drawing 2181 * @since 18 2182 */ 2183 ascent: number; 2184 2185 /** 2186 * Descent of a text line. The value is a floating point number. 2187 * @type { number } 2188 * @syscap SystemCapability.Graphics.Drawing 2189 * @since 18 2190 */ 2191 descent: number; 2192 2193 /** 2194 * Leading of a text line. The value is a floating point number. 2195 * @type { number } 2196 * @syscap SystemCapability.Graphics.Drawing 2197 * @since 18 2198 */ 2199 leading: number; 2200 2201 /** 2202 * Width of the typographic boundaries. The value is a floating point number. 2203 * @type { number } 2204 * @syscap SystemCapability.Graphics.Drawing 2205 * @since 18 2206 */ 2207 width: number; 2208 } 2209 2210 /** 2211 * Defines the callback used to receive the offset and index of each character in a text line object 2212 * as its parameters. 2213 * 2214 * @typedef { function } CaretOffsetsCallback 2215 * @param { number } offset - Offset of each character in a text line. The value is a floating point number. 2216 * @param { number } index - Index of each character in a text line. The value is an integer. 2217 * @param { boolean } leadingEdge - Whether the cursor is located at the front of the character. The value true means 2218 * that the cursor is located at the front of the character, that is, the offset does not contain the character 2219 * width. The value false means that the cursor is located at the rear of the character, that is, the offset 2220 * contains the character width. 2221 * callback function. 2222 * @returns { boolean } Whether to stop calling the callback. The value true means to stop calling the callback, 2223 * and false means to continue calling the callback. 2224 * @syscap SystemCapability.Graphics.Drawing 2225 * @since 18 2226 */ 2227 type CaretOffsetsCallback = (offset: number, index: number, leadingEdge: boolean) => boolean; 2228 2229 /** 2230 * Implements a carrier that describes the basic text line structure of a paragraph. 2231 * Before calling any of the following APIs, you must use getTextLines() of the Paragraph class or createLine() of 2232 * the LineTypeset class to create a TextLine object. 2233 * @syscap SystemCapability.Graphics.Drawing 2234 * @since 12 2235 */ 2236 class TextLine { 2237 /** 2238 * Obtains the number of glyphs in this text line. 2239 * @returns { number } Number of glyphs. The value is an integer. 2240 * @syscap SystemCapability.Graphics.Drawing 2241 * @since 12 2242 */ 2243 getGlyphCount(): number; 2244 2245 /** 2246 * Obtains the range of the text in this text line in the entire paragraph. 2247 * @returns { Range } Range of the text in this text line in the entire paragraph. 2248 * @syscap SystemCapability.Graphics.Drawing 2249 * @since 12 2250 */ 2251 getTextRange(): Range; 2252 2253 /** 2254 * Obtains the array of glyph runs in the text line. 2255 * @returns { Array<Run> } Array of the runs obtained. 2256 * @syscap SystemCapability.Graphics.Drawing 2257 * @since 12 2258 */ 2259 getGlyphRuns(): Array<Run>; 2260 2261 /** 2262 * Paints this text line on the canvas with the coordinate point (x, y) as the upper left corner. 2263 * @param { drawing.Canvas } canvas - Target canvas. 2264 * @param { number } x - X coordinate of the upper left corner. The value is a floating point number. 2265 * @param { number } y - Y coordinate of the upper left corner. The value is a floating point number. 2266 * @syscap SystemCapability.Graphics.Drawing 2267 * @since 12 2268 */ 2269 paint(canvas: drawing.Canvas, x: number, y: number): void; 2270 2271 /** 2272 * Creates a truncated text line object. 2273 * @param { number } width - Width of the line after truncation. The value is a floating point number. 2274 * @param { EllipsisMode } ellipsisMode - Ellipsis mode. Currently, only START and END are supported. 2275 * @param { string } ellipsis - String used to mark a truncation. 2276 * @returns { TextLine } Truncated text line object. 2277 * @syscap SystemCapability.Graphics.Drawing 2278 * @since 18 2279 */ 2280 createTruncatedLine(width: number, ellipsisMode: EllipsisMode, ellipsis: string): TextLine; 2281 2282 /** 2283 * Obtains the typographic boundaries of this text line. These boundaries depend on the typographic font and font 2284 * size, but not on the characters themselves. For example, for the string " a b " (which has a space before 2285 * "a" and a space after "b"), the typographic boundaries include the spaces at the beginning and end of the 2286 * line. Similarly, the strings "j" and "E" have identical typographic boundaries, which are independent of 2287 * the characters themselves. 2288 * @returns { TypographicBounds } Typographic boundaries of the text line. 2289 * @syscap SystemCapability.Graphics.Drawing 2290 * @since 18 2291 */ 2292 getTypographicBounds(): TypographicBounds; 2293 2294 /** 2295 * Obtains the image boundaries of this text line. The image boundaries, equivalent to visual boundaries, depend on 2296 * the font, font size, and characters. For example, for the string " a b " (which has a space before "a" and 2297 * a space after "b"), only "a b" are visible to users, and therefore the image boundaries do not include these 2298 * spaces at the beginning and end of the line. For the strings "j" and "E", their image boundaries are 2299 * different. Specifically, the width of the boundary for "j" is narrower than that for "E", and the height of 2300 * the boundary for "j" is taller than that for "E". 2301 * @returns { common2D.Rect } Image boundary of the text line. 2302 * @syscap SystemCapability.Graphics.Drawing 2303 * @since 18 2304 */ 2305 getImageBounds(): common2D.Rect; 2306 2307 /** 2308 * Obtains the width of the spaces at the end of this text line. 2309 * @returns { number } Number of spaces at the end of the text line. The value is a floating point number. 2310 * @syscap SystemCapability.Graphics.Drawing 2311 * @since 18 2312 */ 2313 getTrailingSpaceWidth(): number; 2314 2315 /** 2316 * Obtains the index of a character at the specified position in the original string. 2317 * @param { common2D.Point } point - Position of the character. 2318 * @returns { number } Index of the character in the text line. The value is an integer. 2319 * @syscap SystemCapability.Graphics.Drawing 2320 * @since 18 2321 */ 2322 getStringIndexForPosition(point: common2D.Point): number; 2323 2324 /** 2325 * Obtains the offset of a character with the specified index in this text line. 2326 * @param { number } index - Index of the character. The value is an integer. 2327 * @returns { number } Offset of the character with the specified index. The value is a floating point number. 2328 * @syscap SystemCapability.Graphics.Drawing 2329 * @since 18 2330 */ 2331 getOffsetForStringIndex(index: number): number; 2332 2333 /** 2334 * Enumerates the offset and index of each character in a text line. 2335 * @param { CaretOffsetsCallback } callback - Custom function, which contains the offset and index of each 2336 * character in the text line. 2337 * @syscap SystemCapability.Graphics.Drawing 2338 * @since 18 2339 */ 2340 enumerateCaretOffsets(callback: CaretOffsetsCallback): void; 2341 2342 /** 2343 * Obtains the offset of this text line after alignment based on the alignment factor and alignment width. 2344 * @param { number } alignmentFactor - Alignment factor, which determines how text is aligned. The value is a 2345 * floating point number. A value less than or equal to 0.0 means that the text is left-aligned; a value 2346 * between 0.0 and 0.5 means that the text is slightly left-aligned; the value 0.5 means that is text 2347 * is centered; a value between 0.5 and 1 means that the text is slightly right-aligned; a value greater than 2348 * or equal to 1.0 means that the text is right-aligned. 2349 * @param { number } alignmentWidth - Alignment width, that is, the width of the text line. The value is a floating 2350 * point number. If the width is less than the actual width of the text line, 0 is returned. 2351 * @returns { number } Offset required for alignment. The value is a floating point number. 2352 * @syscap SystemCapability.Graphics.Drawing 2353 * @since 18 2354 */ 2355 getAlignmentOffset(alignmentFactor: number, alignmentWidth: number): number; 2356 } 2357 2358 /** 2359 * Implements a unit for text layout. 2360 * Before calling any of the following APIs, you must use getGlyphRuns() of the TextLine class to create a Run object. 2361 * @syscap SystemCapability.Graphics.Drawing 2362 * @since 12 2363 */ 2364 class Run { 2365 /** 2366 * Obtains the number of glyphs in this run. 2367 * @returns { number } Number of glyphs. The value is an integer. 2368 * @syscap SystemCapability.Graphics.Drawing 2369 * @since 12 2370 */ 2371 getGlyphCount(): number; 2372 2373 /** 2374 * Obtains the index of each glyph in this run. 2375 * @returns { Array<number> } Array holding the index of each glyph in the run. 2376 * @syscap SystemCapability.Graphics.Drawing 2377 * @since 12 2378 */ 2379 getGlyphs(): Array<number>; 2380 2381 /** 2382 * Obtains the index of each glyph in the specified range of this run. 2383 * @param { Range } range - Range of the glyphs, where range.start indicates the start position of the range, and 2384 * range. end indicates the length of the range. If the length is 0, the range is from range.start to the end 2385 * of the run. If range.end or range.start is set to a negative value, null, or undefined, undefined is 2386 * returned. 2387 * @returns { Array<number> } Array holding the index of each glyph in the run. 2388 * @syscap SystemCapability.Graphics.Drawing 2389 * @since 18 2390 */ 2391 getGlyphs(range: Range): Array<number>; 2392 2393 /** 2394 * Obtains the position of each glyph relative to the respective line in this run. 2395 * @returns { Array<common2D.Point> } Array holding the position of each glyph relative to the respective line in 2396 * the run. 2397 * @syscap SystemCapability.Graphics.Drawing 2398 * @since 12 2399 */ 2400 getPositions(): Array<common2D.Point>; 2401 2402 /** 2403 * Obtains the position array of each glyph relative to the respective line within the specified range of this run. 2404 * @param { Range } range - Range of the glyphs, where range.start indicates the start position of the range, and 2405 * range. end indicates the length of the range. If the length is 0, the range is from range.start to the end of 2406 * the run. If range.end or range.start is set to a negative value, null, or undefined, undefined is returned. 2407 * @returns { Array<common2D.Point> } Array holding the position of each glyph relative to the respective line in 2408 * the run. 2409 * @syscap SystemCapability.Graphics.Drawing 2410 * @since 18 2411 */ 2412 getPositions(range: Range): Array<common2D.Point>; 2413 2414 /** 2415 * Obtains the offset of each glyph in this run relative to its index. 2416 * @returns { Array<common2D.Point> } Array holding the offset of each glyph in the run relative to its index. 2417 * @syscap SystemCapability.Graphics.Drawing 2418 * @since 12 2419 */ 2420 getOffsets(): Array<common2D.Point>; 2421 2422 /** 2423 * Obtains the Font object of this run. 2424 * @returns { drawing.Font } Font object of this run. 2425 * @syscap SystemCapability.Graphics.Drawing 2426 * @since 12 2427 */ 2428 getFont(): drawing.Font; 2429 2430 /** 2431 * Paints this run on the canvas with the coordinate point (x, y) as the upper left corner. 2432 * @param { drawing.Canvas } canvas - Target canvas. 2433 * @param { number } x - X coordinate of the upper left corner. The value is a floating point number. 2434 * @param { number } y - Y coordinate of the upper left corner. The value is a floating point number. 2435 * @syscap SystemCapability.Graphics.Drawing 2436 * @since 12 2437 */ 2438 paint(canvas: drawing.Canvas, x: number, y: number): void; 2439 2440 /** 2441 * Obtains an array of character indices for glyphs within a specified range of this run, where the indices are 2442 * offsets relative to the entire paragraph. 2443 * @param { Range } range - Range of the glyphs, where range.start indicates the start position of the range, and 2444 * range.end indicates the length of the range. If the length is 0, the range is from range.start to the end of 2445 * the run. If range.end or range.start is set to a negative value, null, or undefined, undefined is returned. 2446 * If this parameter is not passed, the entire run is obtained. 2447 * @returns { Array<number> } Array of character indices. 2448 * @syscap SystemCapability.Graphics.Drawing 2449 * @since 18 2450 */ 2451 getStringIndices(range?: Range): Array<number>; 2452 2453 /** 2454 * Obtains the range of glyphs generated by this run. 2455 * @returns { Range } Range of the glyphs, where start indicates the start position of the range, which is the 2456 * index relative to the entire paragraph, and end indicates the length of the range. 2457 * @syscap SystemCapability.Graphics.Drawing 2458 * @since 18 2459 */ 2460 getStringRange(): Range; 2461 2462 /** 2463 * Obtain the typographic boundaries of this run. These boundaries depend on the typographic font and font size, 2464 * but not on the characters themselves. For example, for the string " a b " (which has a space before "a" and 2465 * a space after "b"), the typographic boundaries include the spaces at the beginning and end of the line. 2466 * @returns { TypographicBounds } Typographic boundaries of the run. 2467 * @syscap SystemCapability.Graphics.Drawing 2468 * @since 18 2469 */ 2470 getTypographicBounds(): TypographicBounds; 2471 2472 /** 2473 * Obtains the image boundary of this run. The image boundary, equivalent to a visual boundary, is related to the 2474 * font, font size, and characters. For example, for the string " a b " (which has a space before "a" and a 2475 * space after "b"), only "a b" are visible to users, and therefore the image boundary does not include these 2476 * spaces at the beginning and end. 2477 * @returns { common2D.Rect } Image boundary of the run. 2478 * @syscap SystemCapability.Graphics.Drawing 2479 * @since 18 2480 */ 2481 getImageBounds(): common2D.Rect; 2482 2483 /** 2484 * Obtains the text direction of the run. 2485 * @returns { TextDirection } Returns the text direction. 2486 * @syscap SystemCapability.Graphics.Drawing 2487 * @since 20 2488 */ 2489 getTextDirection(): TextDirection; 2490 2491 /** 2492 * Gets the glyph width array within the range. 2493 * @param { Range } range - Range of the glyphs, where range.start indicates the start position of the range, and 2494 * range.end indicates the length of the range. If the length is 0, the range is from range.start to the end of 2495 * the run. 2496 * @returns { Array<common2D.Point> } Array holding the advance width and height of each glyph. 2497 * @syscap SystemCapability.Graphics.Drawing 2498 * @since 20 2499 */ 2500 getAdvances(range: Range): Array<common2D.Point>; 2501 } 2502 2503 /** 2504 * Describes the layout information and metrics for a continuous piece of text (a run) in a line of text. 2505 * @typedef RunMetrics 2506 * @syscap SystemCapability.Graphics.Drawing 2507 * @since arkts {'1.1':'12','1.2':'20'} 2508 * @arkts 1.1&1.2 2509 */ 2510 interface RunMetrics { 2511 /** 2512 * The metrics of an Font. 2513 * @type { TextStyle } 2514 * @syscap SystemCapability.Graphics.Drawing 2515 * @since arkts {'1.1':'12','1.2':'20'} 2516 * @arkts 1.1&1.2 2517 */ 2518 textStyle: TextStyle; 2519 2520 /** 2521 * Describes text style. 2522 * @type { drawing.FontMetrics } 2523 * @syscap SystemCapability.Graphics.Drawing 2524 * @since arkts {'1.1':'12','1.2':'20'} 2525 * @arkts 1.1&1.2 2526 */ 2527 fontMetrics: drawing.FontMetrics; 2528 } 2529 2530 /** 2531 * Describes the measurement information of a single line of text in the text layout. 2532 * @typedef LineMetrics 2533 * @syscap SystemCapability.Graphics.Drawing 2534 * @since arkts {'1.1':'12','1.2':'20'} 2535 * @arkts 1.1&1.2 2536 */ 2537 interface LineMetrics { 2538 /** 2539 * Start index of the line in the text buffer. 2540 * @type { number } 2541 * @syscap SystemCapability.Graphics.Drawing 2542 * @since arkts {'1.1':'12','1.2':'20'} 2543 * @arkts 1.1&1.2 2544 */ 2545 startIndex: number; 2546 2547 /** 2548 * End index of the line in the text buffer. 2549 * @type { number } 2550 * @syscap SystemCapability.Graphics.Drawing 2551 * @since arkts {'1.1':'12','1.2':'20'} 2552 * @arkts 1.1&1.2 2553 */ 2554 endIndex: number; 2555 2556 /** 2557 * Ascent, that is, the distance from the baseline to the top of the character. 2558 * @type { number } 2559 * @syscap SystemCapability.Graphics.Drawing 2560 * @since arkts {'1.1':'12','1.2':'20'} 2561 * @arkts 1.1&1.2 2562 */ 2563 ascent: number; 2564 2565 /** 2566 * Descent, that is, the distance from the baseline to the bottom of the character. 2567 * @type { number } 2568 * @syscap SystemCapability.Graphics.Drawing 2569 * @since arkts {'1.1':'12','1.2':'20'} 2570 * @arkts 1.1&1.2 2571 */ 2572 descent: number; 2573 2574 /** 2575 * Height of the line, which is Math.round(ascent + descent). 2576 * @type { number } 2577 * @syscap SystemCapability.Graphics.Drawing 2578 * @since arkts {'1.1':'12','1.2':'20'} 2579 * @arkts 1.1&1.2 2580 */ 2581 height: number; 2582 2583 /** 2584 * Width of the line. 2585 * @type { number } 2586 * @syscap SystemCapability.Graphics.Drawing 2587 * @since arkts {'1.1':'12','1.2':'20'} 2588 * @arkts 1.1&1.2 2589 */ 2590 width: number; 2591 2592 /** 2593 * Left edge of the line. The right edge is the value of left plus the value of width. 2594 * @type { number } 2595 * @syscap SystemCapability.Graphics.Drawing 2596 * @since arkts {'1.1':'12','1.2':'20'} 2597 * @arkts 1.1&1.2 2598 */ 2599 left: number; 2600 2601 /** 2602 * Y coordinate of the baseline in the line relative to the top of the paragraph. 2603 * @type { number } 2604 * @syscap SystemCapability.Graphics.Drawing 2605 * @since arkts {'1.1':'12','1.2':'20'} 2606 * @arkts 1.1&1.2 2607 */ 2608 baseline: number; 2609 2610 /** 2611 * Line number, starting from 0. 2612 * @type { number } 2613 * @syscap SystemCapability.Graphics.Drawing 2614 * @since arkts {'1.1':'12','1.2':'20'} 2615 * @arkts 1.1&1.2 2616 */ 2617 lineNumber: number; 2618 2619 /** 2620 * Height from the top to the current line. 2621 * @type { number } 2622 * @syscap SystemCapability.Graphics.Drawing 2623 * @since arkts {'1.1':'12','1.2':'20'} 2624 * @arkts 1.1&1.2 2625 */ 2626 topHeight: number; 2627 2628 /** 2629 * Mapping between text index ranges and the FontMetrics associated with 2630 * them. The first run will be keyed under start_index. The metrics here. 2631 * are before layout and are the base values we calculate from. 2632 * @type { Map<number, RunMetrics> } 2633 * @syscap SystemCapability.Graphics.Drawing 2634 * @since arkts {'1.1':'12','1.2':'20'} 2635 * @arkts 1.1&1.2 2636 */ 2637 runMetrics: Map<number, RunMetrics>; 2638 } 2639 2640 /** 2641 * Obtains the full names of all fonts of the specified type. This API uses a promise to return the result. 2642 * @param { SystemFontType } fontType - System font type. 2643 * @returns { Promise<Array<string>> } Promise used to return the full names of all fonts of the specified type. 2644 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2645 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 2646 * @syscap SystemCapability.Graphics.Drawing 2647 * @since 14 2648 */ 2649 function getSystemFontFullNamesByType(fontType: SystemFontType): Promise<Array<string>>; 2650 2651 /** 2652 * Obtains the font descriptor based on the font name and type. This API uses a promise to return the result. 2653 * A font descriptor is a data structure that describes font features. It contains details of the font appearance and 2654 * properties. 2655 * @param { string } fullName - Font name, corresponding to the value of fullName in the name table of the 2656 * corresponding font file. It is obtained by calling getSystemFontFullNamesByType. 2657 * @param { SystemFontType } fontType - System font type. 2658 * @returns { Promise<FontDescriptor> } Promise used to return the font descriptor. 2659 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2660 * <br>2. Incorrect parameter types. 2661 * @syscap SystemCapability.Graphics.Drawing 2662 * @since 14 2663 */ 2664 function getFontDescriptorByFullName(fullName: string, fontType: SystemFontType): Promise<FontDescriptor>; 2665 2666 /** 2667 * Obtains all system font descriptors that match the provided font descriptor. This API uses a promise to return the 2668 * result. 2669 * @param { FontDescriptor } desc - Font descriptor to match against. If this parameter is left unspecified, 2670 * all system font descriptors are returned. If a specific value is provided, the matching is performed based on 2671 * <br.the value provided. If the matching fails, an empty array is returned. 2672 * @returns { Promise<Array<FontDescriptor>> } Promise used to return all matched system font descriptors, and an 2673 * empty array will be returned if the matching fails. 2674 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2675 * <br>2. Incorrect parameter types; 3. Parameter verification failed. 2676 * @syscap SystemCapability.Graphics.Drawing 2677 * @since 18 2678 */ 2679 function matchFontDescriptors(desc: FontDescriptor): Promise<Array<FontDescriptor>>; 2680 2681 /** 2682 * Implements a paragraph-style text tab, which stores the alignment mode and position. 2683 * @typedef TextTab 2684 * @syscap SystemCapability.Graphics.Drawing 2685 * @since arkts {'1.1':'18','1.2':'20'} 2686 * @arkts 1.1&1.2 2687 */ 2688 interface TextTab { 2689 /** 2690 * Alignment mode of the text following the tab character in a paragraph. It can be set to LEFT, RIGHT, and CENTER 2691 * defined in TextAlign. Other enumerated values have the effect of left alignment. The default value is left 2692 * alignment. 2693 * @type { TextAlign } 2694 * @syscap SystemCapability.Graphics.Drawing 2695 * @since arkts {'1.1':'18','1.2':'20'} 2696 * @arkts 1.1&1.2 2697 */ 2698 alignment: TextAlign; 2699 2700 /** 2701 * Alignment position of the text following the tab character. The value is a floating point number, in px. 2702 * The minimum value is 1.0. When the value is less than 1.0, the tab character is replaced with a space. 2703 * @type { number } 2704 * @syscap SystemCapability.Graphics.Drawing 2705 * @since arkts {'1.1':'18','1.2':'20'} 2706 * @arkts 1.1&1.2 2707 */ 2708 location: number; 2709 } 2710 2711 /** 2712 * Defines text rendering high contrast mode to enhance readability. 2713 * @enum { number } 2714 * @syscap SystemCapability.Graphics.Drawing 2715 * @since 20 2716 */ 2717 enum TextHighContrast { 2718 /** 2719 * Follow system's high contrast settings for text rendering. 2720 * @syscap SystemCapability.Graphics.Drawing 2721 * @since 20 2722 */ 2723 TEXT_FOLLOW_SYSTEM_HIGH_CONTRAST, 2724 /** 2725 * Disables high contrast rendering regardless of system settings. 2726 * @syscap SystemCapability.Graphics.Drawing 2727 * @since 20 2728 */ 2729 TEXT_APP_DISABLE_HIGH_CONTRAST, 2730 /** 2731 * Enable high contrast rendering regardless of system settings. 2732 * @syscap SystemCapability.Graphics.Drawing 2733 * @since 20 2734 */ 2735 TEXT_APP_ENABLE_HIGH_CONTRAST, 2736 } 2737 2738 /** 2739 * Sets high contrast mode of text rendering. 2740 * @param { TextHighContrast } action - High contrast mode. 2741 * @syscap SystemCapability.Graphics.Drawing 2742 * @since 20 2743 */ 2744 function setTextHighContrast(action: TextHighContrast): void; 2745 2746 /** 2747 * Visual representations for undefined (.notdef) glyphs. 2748 * 2749 * @enum { number } 2750 * @syscap SystemCapability.Graphics.Drawing 2751 * @since 20 2752 */ 2753 enum TextUndefinedGlyphDisplay { 2754 /** 2755 * Use the font's built-in .notdef glyph. This respects font's internal .notdef glyph design, 2756 * which might be an empty box, blank space, or custom symbol. 2757 * @syscap SystemCapability.Graphics.Drawing 2758 * @since 20 2759 */ 2760 USE_DEFAULT, 2761 /** 2762 * Always replace undefined glyphs with explicit tofu blocks, 2763 * overriding the font's default behavior. Useful for debugging missing characters 2764 * or enforcing consistent missing symbol display. 2765 * @syscap SystemCapability.Graphics.Drawing 2766 * @since 20 2767 */ 2768 USE_TOFU, 2769 } 2770 2771 /** 2772 * Sets the glyph type to use when a character maps to the .notdef (undefined) glyph. 2773 * affects all text rendered after this call. 2774 * This configuration affects how the renderer displays characters that are not defined in the font: 2775 * - The default behavior follows font's internal .notdef glyph design 2776 * - Tofu blocks explicitly show missing characters as visible squares 2777 * @param { TextUndefinedGlyphDisplay } noGlyphShow - The strategy for handling undefined glyphs. 2778 * @syscap SystemCapability.Graphics.Drawing 2779 * @since 20 2780 */ 2781 function setTextUndefinedGlyphDisplay(noGlyphShow: TextUndefinedGlyphDisplay): void; 2782} 2783 2784export default text; 2785