1 /* 2 * Copyright (c) 2021-2022 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 #ifndef C_INCLUDE_DRAWING_TEXT_TYPOGRAPHY_H 17 #define C_INCLUDE_DRAWING_TEXT_TYPOGRAPHY_H 18 19 /** 20 * @addtogroup Drawing 21 * @{ 22 * 23 * @brief Provides the 2D drawing capability. 24 * 25 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 26 * 27 * @since 8 28 * @version 1.0 29 */ 30 31 /** 32 * @file drawing_text_typography.h 33 * 34 * @brief Declares functions related to <b>typography</b> in the drawing module. 35 * 36 * @since 8 37 * @version 1.0 38 */ 39 40 #include "cstddef" 41 #include "drawing_canvas.h" 42 #include "drawing_color.h" 43 #include "drawing_text_declaration.h" 44 #include "drawing_types.h" 45 46 #include "stdint.h" 47 48 #ifdef __cplusplus 49 extern "C" { 50 #endif 51 52 /** 53 * @brief Enumerates text directions. 54 */ 55 enum OH_Drawing_TextDirection { 56 /** Right to left (RTL) */ 57 TEXT_DIRECTION_RTL, 58 /** Left to right (LTR) */ 59 TEXT_DIRECTION_LTR, 60 }; 61 62 /** 63 * @brief Enumerates text alignment modes. 64 */ 65 enum OH_Drawing_TextAlign { 66 /** Left-aligned */ 67 TEXT_ALIGN_LEFT, 68 /** Right-aligned */ 69 TEXT_ALIGN_RIGHT, 70 /** Center-aligned */ 71 TEXT_ALIGN_CENTER, 72 /** 73 * Justified, which means that each line (except the last line) is stretched so that every line has equal width, 74 * and the left and right margins are straight. 75 */ 76 TEXT_ALIGN_JUSTIFY, 77 /** 78 * <b>TEXT_ALIGN_START</b> achieves the same effect as <b>TEXT_ALIGN_LEFT</b> 79 * when <b>OH_Drawing_TextDirection</b> is <b>TEXT_DIRECTION_LTR</b>; 80 * it achieves the same effect as <b>TEXT_ALIGN_RIGHT</b> 81 * when <b>OH_Drawing_TextDirection</b> is <b>TEXT_DIRECTION_RTL</b>. 82 */ 83 TEXT_ALIGN_START, 84 /** 85 * <b>TEXT_ALIGN_END</b> achieves the same effect as <b>TEXT_ALIGN_RIGHT</b> 86 * when <b>OH_Drawing_TextDirection</b> is <b>TEXT_DIRECTION_LTR</b>; 87 * it achieves the same effect as <b>TEXT_ALIGN_LEFT</b> 88 * when <b>OH_Drawing_TextDirection</b> is <b>TEXT_DIRECTION_RTL</b>. 89 */ 90 TEXT_ALIGN_END, 91 }; 92 93 /** 94 * @brief Enumerates font weights. 95 */ 96 enum OH_Drawing_FontWeight { 97 /** Thin */ 98 FONT_WEIGHT_100, 99 /** Extra-light */ 100 FONT_WEIGHT_200, 101 /** Light */ 102 FONT_WEIGHT_300, 103 /** Normal/Regular */ 104 FONT_WEIGHT_400, 105 /** Medium*/ 106 FONT_WEIGHT_500, 107 /** Semi-bold */ 108 FONT_WEIGHT_600, 109 /** Bold */ 110 FONT_WEIGHT_700, 111 /** Extra-bold */ 112 FONT_WEIGHT_800, 113 /** Black */ 114 FONT_WEIGHT_900, 115 }; 116 117 /** 118 * @brief Enumerates text baselines. 119 */ 120 enum OH_Drawing_TextBaseline { 121 /** Alphabetic, where the letters in alphabets like English sit on. */ 122 TEXT_BASELINE_ALPHABETIC, 123 /** Ideographic. The baseline is at the bottom of the text area. */ 124 TEXT_BASELINE_IDEOGRAPHIC, 125 }; 126 127 /** 128 * @brief Enumerates text decorations. 129 */ 130 enum OH_Drawing_TextDecoration { 131 /** No decoration. */ 132 TEXT_DECORATION_NONE = 0x0, 133 /** A underline is used for decoration. */ 134 TEXT_DECORATION_UNDERLINE = 0x1, 135 /** An overline is used for decoration. */ 136 TEXT_DECORATION_OVERLINE = 0x2, 137 /** A strikethrough is used for decoration. */ 138 TEXT_DECORATION_LINE_THROUGH = 0x4, 139 }; 140 141 /** 142 * @brief Enumerates font styles. 143 */ 144 enum OH_Drawing_FontStyle { 145 /** Normal style */ 146 FONT_STYLE_NORMAL, 147 /** Italic style */ 148 FONT_STYLE_ITALIC, 149 }; 150 151 /** 152 * @brief Creates an <b>OH_Drawing_TypographyStyle</b> object. 153 * 154 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 155 * @return Returns the pointer to the <b>OH_Drawing_TypographyStyle</b> object created. 156 * @since 8 157 * @version 1.0 158 */ 159 OH_Drawing_TypographyStyle* OH_Drawing_CreateTypographyStyle(void); 160 161 /** 162 * @brief Releases the memory occupied by an <b>OH_Drawing_TypographyStyle</b> object. 163 * 164 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 165 * @param OH_Drawing_TypographyStyle Indicates the pointer to an <b>OH_Drawing_TypographyStyle</b> object. 166 * @since 8 167 * @version 1.0 168 */ 169 void OH_Drawing_DestroyTypographyStyle(OH_Drawing_TypographyStyle*); 170 171 /** 172 * @brief Sets the text direction. 173 * 174 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 175 * @param OH_Drawing_TypographyStyle Indicates the pointer to an <b>OH_Drawing_TypographyStyle</b> object. 176 * @param int Indicates the text direction to set. For details, see the enum <b>OH_Drawing_TextDirection</b>. 177 * @since 8 178 * @version 1.0 179 */ 180 void OH_Drawing_SetTypographyTextDirection(OH_Drawing_TypographyStyle*, int /* OH_Drawing_TextDirection */); 181 182 /** 183 * @brief Sets the text alignment mode. 184 * 185 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 186 * @param OH_Drawing_TypographyStyle Indicates the pointer to an <b>OH_Drawing_TypographyStyle</b> object. 187 * @param int Indicates the text alignment mode to set. For details, see the enum <b>OH_Drawing_TextAlign</b>. 188 * @since 8 189 * @version 1.0 190 */ 191 void OH_Drawing_SetTypographyTextAlign(OH_Drawing_TypographyStyle*, int /* OH_Drawing_TextAlign */); 192 193 /** 194 * @brief Sets the maximum number of lines in a text file. 195 * 196 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 197 * @param OH_Drawing_TypographyStyle Indicates the pointer to an <b>OH_Drawing_TypographyStyle</b> object. 198 * @param int Indicates the maximum number of lines to set. 199 * @since 8 200 * @version 1.0 201 */ 202 void OH_Drawing_SetTypographyTextMaxLines(OH_Drawing_TypographyStyle*, int /* maxLines */); 203 204 /** 205 * @brief Creates an <b>OH_Drawing_TextStyle</b> object. 206 * 207 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 208 * @return Returns the pointer to the <b>OH_Drawing_TextStyle</b> object created. 209 * @since 8 210 * @version 1.0 211 */ 212 OH_Drawing_TextStyle* OH_Drawing_CreateTextStyle(void); 213 214 /** 215 * @brief Releases the memory occupied by an <b>OH_Drawing_TextStyle</b> object. 216 * 217 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 218 * @param OH_Drawing_TextStyle Indicates the pointer to an <b>OH_Drawing_TextStyle</b> object. 219 * @since 8 220 * @version 1.0 221 */ 222 void OH_Drawing_DestroyTextStyle(OH_Drawing_TextStyle*); 223 224 /** 225 * @brief Sets the text color. 226 * 227 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 228 * @param OH_Drawing_TextStyle Indicates the pointer to an <b>OH_Drawing_TextStyle</b> object. 229 * @param uint32_t Indicates the color to set. 230 * @since 8 231 * @version 1.0 232 */ 233 void OH_Drawing_SetTextStyleColor(OH_Drawing_TextStyle*, uint32_t /* color */); 234 235 /** 236 * @brief Sets the font size. 237 * 238 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 239 * @param OH_Drawing_TextStyle Indicates the pointer to an <b>OH_Drawing_TextStyle</b> object. 240 * @param double Indicates the font size to set. 241 * @since 8 242 * @version 1.0 243 */ 244 void OH_Drawing_SetTextStyleFontSize(OH_Drawing_TextStyle*, double /* fontSize */); 245 246 /** 247 * @brief Sets the font weight. 248 * 249 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 250 * @param OH_Drawing_TextStyle Indicates the pointer to an <b>OH_Drawing_TextStyle</b> object. 251 * @param int Indicates the font weight to set. For details, see the enum <b>OH_Drawing_FontWeight</b>. 252 * @since 8 253 * @version 1.0 254 */ 255 void OH_Drawing_SetTextStyleFontWeight(OH_Drawing_TextStyle*, int /* OH_Drawing_FontWeight */); 256 257 /** 258 * @brief Sets the text baseline. 259 * 260 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 261 * @param OH_Drawing_TextStyle Indicates the pointer to an <b>OH_Drawing_TextStyle</b> object. 262 * @param int Indicates the text baseline to set. For details, see the enum <b>OH_Drawing_TextBaseline</b>. 263 * @since 8 264 * @version 1.0 265 */ 266 void OH_Drawing_SetTextStyleBaseLine(OH_Drawing_TextStyle*, int /* OH_Drawing_TextBaseline */); 267 268 /** 269 * @brief Sets the text decoration. 270 * 271 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 272 * @param OH_Drawing_TextStyle Indicates the pointer to an <b>OH_Drawing_TextStyle</b> object. 273 * @param int Indicates the text decoration to set. For details, see the enum <b>OH_Drawing_TextDecoration</b>. 274 * @since 8 275 * @version 1.0 276 */ 277 void OH_Drawing_SetTextStyleDecoration(OH_Drawing_TextStyle*, int /* OH_Drawing_TextDecoration */); 278 279 /** 280 * @brief Sets the color for the text decoration. 281 * 282 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 283 * @param OH_Drawing_TextStyle Indicates the pointer to an <b>OH_Drawing_TextStyle</b> object. 284 * @param uint32_t Indicates the color to set. 285 * @since 8 286 * @version 1.0 287 */ 288 void OH_Drawing_SetTextStyleDecorationColor(OH_Drawing_TextStyle*, uint32_t /* color */); 289 290 /** 291 * @brief Sets the font height. 292 * 293 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 294 * @param OH_Drawing_TextStyle Indicates the pointer to an <b>OH_Drawing_TextStyle</b> object. 295 * @param double Indicates the font height to set. 296 * @since 8 297 * @version 1.0 298 */ 299 void OH_Drawing_SetTextStyleFontHeight(OH_Drawing_TextStyle*, double /* fontHeight */); 300 301 /** 302 * @brief Sets the font families. 303 * 304 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 305 * @param OH_Drawing_TextStyle Indicates the pointer to an <b>OH_Drawing_TextStyle</b> object. 306 * @param int Indicates the number of font families to set. 307 * @param char Indicates the pointer to the font families to set. 308 * @since 8 309 * @version 1.0 310 */ 311 void OH_Drawing_SetTextStyleFontFamilies(OH_Drawing_TextStyle*, 312 int /* fontFamiliesNumber */, const char* fontFamilies[]); 313 314 /** 315 * @brief Sets the font style. 316 * 317 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 318 * @param OH_Drawing_TextStyle Indicates the pointer to an <b>OH_Drawing_TextStyle</b> object. 319 * @param int Indicates the font style to set. For details, see the enum <b>OH_Drawing_FontStyle</b>. 320 * @since 8 321 * @version 1.0 322 */ 323 void OH_Drawing_SetTextStyleFontStyle(OH_Drawing_TextStyle*, int /* OH_Drawing_FontStyle */); 324 325 /** 326 * @brief Sets the locale. 327 * 328 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 329 * @param OH_Drawing_TextStyle Indicates the pointer to an <b>OH_Drawing_TextStyle</b> object. 330 * @param char Indicates the pointer to the locale to set. 331 * @since 8 332 * @version 1.0 333 */ 334 void OH_Drawing_SetTextStyleLocale(OH_Drawing_TextStyle*, const char*); 335 336 /** 337 * @brief Creates a pointer to an <b>OH_Drawing_TypographyCreate</b> object. 338 * 339 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 340 * @param OH_Drawing_TypographyStyle Indicates the pointer to an <b>OH_Drawing_TypographyStyle</b> object. 341 * @param OH_Drawing_FontCollection Indicates the pointer to an <b>OH_Drawing_FontCollection</b> object. 342 * @return Returns the pointer to the <b>OH_Drawing_TypographyCreate</b> object created. 343 * @since 8 344 * @version 1.0 345 */ 346 OH_Drawing_TypographyCreate* OH_Drawing_CreateTypographyHandler(OH_Drawing_TypographyStyle*, 347 OH_Drawing_FontCollection*); 348 349 /** 350 * @brief Releases the memory occupied by an <b>OH_Drawing_TypographyCreate</b> object. 351 * 352 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 353 * @param OH_Drawing_TypographyCreate Indicates the pointer to an <b>OH_Drawing_TypographyCreate</b> object. 354 * @since 8 355 * @version 1.0 356 */ 357 void OH_Drawing_DestroyTypographyHandler(OH_Drawing_TypographyCreate*); 358 359 /** 360 * @brief Sets the text style. 361 * 362 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 363 * @param OH_Drawing_TypographyCreate Indicates the pointer to an <b>OH_Drawing_TypographyCreate</b> object. 364 * @param OH_Drawing_TextStyle Indicates the pointer to an <b>OH_Drawing_TextStyle</b> object. 365 * @since 8 366 * @version 1.0 367 */ 368 void OH_Drawing_TypographyHandlerPushTextStyle(OH_Drawing_TypographyCreate*, OH_Drawing_TextStyle*); 369 370 /** 371 * @brief Sets the text content. 372 * 373 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 374 * @param OH_Drawing_TypographyCreate Indicates the pointer to an <b>OH_Drawing_TypographyCreate</b> object. 375 * @param char Indicates the pointer to the text content to set. 376 * @since 8 377 * @version 1.0 378 */ 379 void OH_Drawing_TypographyHandlerAddText(OH_Drawing_TypographyCreate*, const char*); 380 381 /** 382 * @brief Removes the topmost style in the stack, leaving the remaining styles in effect. 383 * 384 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 385 * @param OH_Drawing_TypographyCreate Indicates the pointer to an <b>OH_Drawing_TypographyCreate</b> object. 386 * @since 8 387 * @version 1.0 388 */ 389 void OH_Drawing_TypographyHandlerPopTextStyle(OH_Drawing_TypographyCreate*); 390 391 /** 392 * @brief Creates an <b>OH_Drawing_Typography</b> object. 393 * 394 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 395 * @param OH_Drawing_TypographyCreate Indicates the pointer to an <b>OH_Drawing_TypographyCreate</b> object. 396 * @return Returns the pointer to the <b>OH_Drawing_Typography</b> object created. 397 * @since 8 398 * @version 1.0 399 */ 400 OH_Drawing_Typography* OH_Drawing_CreateTypography(OH_Drawing_TypographyCreate*); 401 402 /** 403 * @brief Releases the memory occupied by an <b>OH_Drawing_Typography</b> object. 404 * 405 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 406 * @param OH_Drawing_Typography Indicates the pointer to an <b>OH_Drawing_Typography</b> object. 407 * @since 8 408 * @version 1.0 409 */ 410 void OH_Drawing_DestroyTypography(OH_Drawing_Typography*); 411 412 /** 413 * @brief Lays out the typography. 414 * 415 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 416 * @param OH_Drawing_Typography Indicates the pointer to an <b>OH_Drawing_Typography</b> object. 417 * @param double Indicates the maximum text width to set. 418 * @since 8 419 * @version 1.0 420 */ 421 void OH_Drawing_TypographyLayout(OH_Drawing_Typography*, double /* maxWidth */); 422 423 /** 424 * @brief Paints text on the canvas. 425 * 426 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 427 * @param OH_Drawing_Typography Indicates the pointer to an <b>OH_Drawing_Typography</b> object. 428 * @param OH_Drawing_Canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 429 * @param double Indicates the x coordinate. 430 * @param double Indicates the y coordinate. 431 * @since 8 432 * @version 1.0 433 */ 434 void OH_Drawing_TypographyPaint(OH_Drawing_Typography*, OH_Drawing_Canvas*, 435 double /* potisionX */, double /* potisionY */); 436 437 /** 438 * @brief Gets the max width. 439 * 440 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 441 * @param OH_Drawing_Typography Indicates the pointer to an <b>OH_Drawing_Typography</b> object. 442 * @return Returns the max width. 443 * @since 9 444 * @version 1.1 445 */ 446 double OH_Drawing_TypographyGetMaxWidth(OH_Drawing_Typography*); 447 448 /** 449 * @brief Gets the height. 450 * 451 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 452 * @param OH_Drawing_Typography Indicates the pointer to an <b>OH_Drawing_Typography</b> object. 453 * @return Returns the height. 454 * @since 9 455 * @version 1.1 456 */ 457 double OH_Drawing_TypographyGetHeight(OH_Drawing_Typography*); 458 459 /** 460 * @brief Gets the longest line. 461 * 462 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 463 * @param OH_Drawing_Typography Indicates the pointer to an <b>OH_Drawing_Typography</b> object. 464 * @return Returns the length of the longest line. 465 * @since 9 466 * @version 1.1 467 */ 468 double OH_Drawing_TypographyGetLongestLine(OH_Drawing_Typography*); 469 470 /** 471 * @brief Gets the min intrinsic width. 472 * 473 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 474 * @param OH_Drawing_Typography Indicates the pointer to an <b>OH_Drawing_Typography</b> object. 475 * @return Returns the min intrinsic width. 476 * @since 9 477 * @version 1.1 478 */ 479 double OH_Drawing_TypographyGetMinIntrinsicWidth(OH_Drawing_Typography*); 480 481 /** 482 * @brief Gets the max intrinsic width. 483 * 484 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 485 * @param OH_Drawing_Typography Indicates the pointer to an <b>OH_Drawing_Typography</b> object. 486 * @return Returns the max intrinsic width. 487 * @since 9 488 * @version 1.1 489 */ 490 double OH_Drawing_TypographyGetMaxIntrinsicWidth(OH_Drawing_Typography*); 491 492 /** 493 * @brief Gets the alphabetic baseline. 494 * 495 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 496 * @param OH_Drawing_Typography Indicates the pointer to an <b>OH_Drawing_Typography</b> object. 497 * @return Returns the alphabetic baseline. 498 * @since 9 499 * @version 1.1 500 */ 501 double OH_Drawing_TypographyGetAlphabeticBaseline(OH_Drawing_Typography*); 502 503 /** 504 * @brief Gets the ideographic baseline. 505 * 506 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 507 * @param OH_Drawing_Typography Indicates the pointer to an <b>OH_Drawing_Typography</b> object. 508 * @return Returns the ideographic baseline. 509 * @since 9 510 * @version 1.1 511 */ 512 double OH_Drawing_TypographyGetIdeographicBaseline(OH_Drawing_Typography*); 513 514 #ifdef __cplusplus 515 } 516 #endif 517 /** @} */ 518 #endif