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 * @addtogroup Drawing 18 * @{ 19 * 20 * @brief Provides the text run capability. 21 * 22 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 23 * 24 * @since 18 25 * @version 1.0 26 */ 27 28 /** 29 * @file drawing_text_run.h 30 * 31 * @brief Declares functions related to <b>run</b> in the drawing module. 32 * 33 * @kit ArkGraphics2D 34 * @library libnative_drawing.so 35 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 36 * @since 18 37 * @version 1.0 38 */ 39 40 #ifndef C_INCLUDE_DRAWING_TEXT_RUN_H 41 #define C_INCLUDE_DRAWING_TEXT_RUN_H 42 43 #include "drawing_text_declaration.h" 44 #include "drawing_text_typography.h" 45 #include "drawing_types.h" 46 47 #ifdef __cplusplus 48 extern "C" { 49 #endif 50 /** 51 * @brief Gets the run glyph indices ,the offset of the index relative to the entire paragraph. 52 * 53 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 54 * @param run Indicates the pointer to an <b>OH_Drawing_Run</b> object. 55 * @param start The run of start index. 56 * @param length The run of length, if start and length are set to 0, then get all of the current run. 57 * @return Run of glyph indices array object <b>OH_Drawing_Array</b>. 58 * @since 18 59 */ 60 OH_Drawing_Array* OH_Drawing_GetRunStringIndices(OH_Drawing_Run* run, int64_t start, int64_t length); 61 62 /** 63 * @brief Gets the run glyph indices by index. 64 * 65 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 66 * @param stringIndices the run glyph indices array object <b>OH_Drawing_Array</b>. 67 * @param index The run of glyph index. 68 * @return Run of glyph indices element. 69 * @since 18 70 */ 71 uint64_t OH_Drawing_GetRunStringIndicesByIndex(OH_Drawing_Array* stringIndices, size_t index); 72 73 /** 74 * @brief Releases the memory run glyph indices array. 75 * 76 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 77 * @param stringIndices glyph indices array object <b>OH_Drawing_Array</b>. 78 * @since 18 79 */ 80 void OH_Drawing_DestroyRunStringIndices(OH_Drawing_Array* stringIndices); 81 82 /** 83 * @brief Gets the range run glyph location and length. 84 * 85 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 86 * @param run Indicates the pointer to an <b>OH_Drawing_Run</b> object. 87 * @param location The run of glyph location. 88 * @param length The run of glyph length. 89 * @since 18 90 */ 91 void OH_Drawing_GetRunStringRange(OH_Drawing_Run* run, uint64_t* location, uint64_t* length); 92 93 /** 94 * @brief Gets the run typographic bound. 95 * 96 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 97 * @param run Indicates the pointer to an <b>OH_Drawing_Run</b> object. 98 * @param ascent The run of ascent. 99 * @param descent The run of descent. 100 * @param leading The run of leading. 101 * @return run typographic width. 102 * @since 18 103 */ 104 float OH_Drawing_GetRunTypographicBounds(OH_Drawing_Run* run, float* ascent, float* descent, float* leading); 105 106 /** 107 * @brief Paints text on the canvas. 108 * 109 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 110 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 111 * @param run Indicates the pointer to an <b>OH_Drawing_Run</b> object. 112 * @param x Indicates the x coordinate. 113 * @param y Indicates the y coordinate. 114 * @since 18 115 */ 116 void OH_Drawing_RunPaint(OH_Drawing_Canvas* canvas, OH_Drawing_Run* run, double x, double y); 117 118 /** 119 * @brief Gets the run image bound. 120 * 121 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 122 * @param run Indicates the pointer to an <b>OH_Drawing_Run</b> object. 123 * @return The run image bounds to an <b>OH_Drawing_Rect</b> object. 124 * @since 18 125 */ 126 OH_Drawing_Rect* OH_Drawing_GetRunImageBounds(OH_Drawing_Run* run); 127 128 /** 129 * @brief Releases the memory run image bounds pointer. 130 * 131 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 132 * @param rect Run image bounds to an <b>OH_Drawing_Rect</b> object. 133 * @since 18 134 */ 135 void OH_Drawing_DestroyRunImageBounds(OH_Drawing_Rect* rect); 136 137 /** 138 * @brief Gets the range glyph identifier for each character. 139 * 140 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 141 * @param run Indicates the pointer to an <b>OH_Drawing_Run</b> object. 142 * @param start The run of start index. 143 * @param length The run of length, if start and length are set to 0, then get all of the current run. 144 * @return Run of glyph array object <b>OH_Drawing_Array</b. 145 * @since 18 146 */ 147 OH_Drawing_Array* OH_Drawing_GetRunGlyphs(OH_Drawing_Run* run, int64_t start, int64_t length); 148 149 /** 150 * @brief Gets the glyph identifier by index. 151 * 152 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 153 * @param glyphs The run of glyph array object <b>OH_Drawing_Array</b>. 154 * @param index The run of glyph index. 155 * @return Run of glyph element. 156 * @since 18 157 * @version 1.0 158 */ 159 uint16_t OH_Drawing_GetRunGlyphsByIndex(OH_Drawing_Array* glyphs, size_t index); 160 161 /** 162 * @brief Releases the memory run glyph array. 163 * 164 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 165 * @param glyphs The run of glyph array object <b>OH_Drawing_Array</b>. 166 * @since 18 167 */ 168 void OH_Drawing_DestroyRunGlyphs(OH_Drawing_Array* glyphs); 169 170 /** 171 * @brief Gets the range glyph position array. 172 * 173 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 174 * @param run Indicates the pointer to an <b>OH_Drawing_Run</b> object. 175 * @param start The run of start index. 176 * @param length The run of length, if start and length are set to 0, then get all of the current run. 177 * @return Run of position array object <b>OH_Drawing_Array</b>. 178 * @since 18 179 */ 180 OH_Drawing_Array* OH_Drawing_GetRunPositions(OH_Drawing_Run* run, int64_t start, int64_t length); 181 182 /** 183 * @brief Gets the glyph position by index. 184 * 185 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 186 * @param positions The run of position array object <b>OH_Drawing_Array</b>. 187 * @param index The run of glyph index. 188 * @return Run of glyph position pointer to an <b>OH_Drawing_Point</b> object. 189 * @since 18 190 * @version 1.0 191 */ 192 OH_Drawing_Point* OH_Drawing_GetRunPositionsByIndex(OH_Drawing_Array* positions, size_t index); 193 194 /** 195 * @brief Releases the memory run of position array. 196 * 197 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 198 * @param positions The run of position array object <b>OH_Drawing_Array</b>. 199 * @since 18 200 */ 201 void OH_Drawing_DestroyRunPositions(OH_Drawing_Array* positions); 202 203 /** 204 * @brief Gets the number of glyph. 205 * 206 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 207 * @param run Indicates the pointer to an <b>OH_Drawing_Run</b> object. 208 * @return The number of glyph. 209 * @since 18 210 */ 211 uint32_t OH_Drawing_GetRunGlyphCount(OH_Drawing_Run* run); 212 213 /** 214 * @brief Gets the Font Object of run. 215 * 216 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 217 * @param run Indicates the pointer to an <b>OH_Drawing_Run</b> object. 218 * @return The Font Object of run. 219 * @since 20 220 * @version 1.0 221 */ 222 OH_Drawing_Font* OH_Drawing_GetRunFont(OH_Drawing_Run* run); 223 224 /** 225 * @brief Get the text direction. 226 * 227 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 228 * @param run Indicates the pointer to an <b>OH_Drawing_Run</b> object. 229 * @return Return the text direction of an <b>OH_Drawing_TextDirection</b> object. 230 * @since 20 231 */ 232 OH_Drawing_TextDirection OH_Drawing_GetRunTextDirection(OH_Drawing_Run* run); 233 234 /** 235 * @brief Gets the glyph advance array. 236 * 237 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 238 * @param run Indicates the pointer to an <b>OH_Drawing_Run</b> object. 239 * @param start The run of start index. 240 * @param length The run of length, if start and length are set to 0, then get all of the current run. 241 * @return Indicates the pointer to the glyph advance array object <b>OH_Drawing_Array</b>. 242 * @since 20 243 */ 244 OH_Drawing_Array* OH_Drawing_GetRunGlyphAdvances(OH_Drawing_Run* run, uint32_t start, uint32_t length); 245 246 /** 247 * @brief Gets the glyph advance by index. 248 * 249 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 250 * @param advances The glyph advance array object <b>OH_Drawing_Array</b>. 251 * @param index The run of glyph index. 252 * @return Run of glyph advance pointer to an <b>OH_Drawing_Point</b> object. 253 * @since 20 254 */ 255 OH_Drawing_Point* OH_Drawing_GetRunGlyphAdvanceByIndex(OH_Drawing_Array* advances, size_t index); 256 257 /** 258 * @brief Releases the memory of glyph advance array. 259 * 260 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 261 * @param advances The run of glyph advance array object <b>OH_Drawing_Array</b>. 262 * @since 20 263 */ 264 void OH_Drawing_DestroyRunGlyphAdvances(OH_Drawing_Array* advances); 265 #ifdef __cplusplus 266 } 267 #endif 268 /** @} */ 269 #endif // C_INCLUDE_DRAWING_TEXT_RUN_H 270