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 2D drawing capability. 21 * 22 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 23 * 24 * @since 14 25 * @version 1.0 26 */ 27 28 /** 29 * @file drawing_text_line.h 30 * 31 * @brief Declares functions related to <b>textLine</b> in the drawing module. 32 * 33 * @since 14 34 * @version 1.0 35 */ 36 37 #ifndef C_INCLUDE_DRAWING_TEXT_LINE_H 38 #define C_INCLUDE_DRAWING_TEXT_LINE_H 39 40 #include "drawing_text_declaration.h" 41 #include "drawing_types.h" 42 43 #ifdef __cplusplus 44 extern "C" { 45 #endif 46 47 /** 48 * @brief Get text line information. 49 * 50 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 51 * @param typography Indicates the pointer to a typography object <b>OH_Drawing_Typography</b>. 52 * @return Indicates the pointer to a text line array object <b>OH_Drawing_Array</b>. 53 * @since 14 54 */ 55 OH_Drawing_Array* OH_Drawing_TypographyGetTextLines(OH_Drawing_Typography* typography); 56 57 /** 58 * @brief Releases the memory occupied by the text line array object <b>OH_Drawing_Array</b>. 59 * 60 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 61 * @param lines Indicates the pointer to the text line array object <b>OH_Drawing_Array</b>. 62 * @since 14 63 * @version 1.0 64 */ 65 void OH_Drawing_DestroyTextLines(OH_Drawing_Array* lines); 66 67 /** 68 * @brief Releases the memory occupied by the text line object <b>OH_Drawing_TextLine</b>. 69 * 70 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 71 * @param line Indicates the pointer to the text line object <b>OH_Drawing_TextLine</b>. 72 * @since 14 73 * @version 1.0 74 */ 75 void OH_Drawing_DestroyTextLine(OH_Drawing_TextLine* line); 76 77 /** 78 * @brief Get the text line object by index. 79 * 80 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 81 * @param lines Indicates the pointer to the text line array object <b>OH_Drawing_Array</b>. 82 * @param index The text line object index. 83 * @return Indicates the pointer to a text line object <b>OH_Drawing_TextLine</b>. 84 * @since 14 85 */ 86 OH_Drawing_TextLine* OH_Drawing_GetTextLineByIndex(OH_Drawing_Array* lines, size_t index); 87 88 /** 89 * @brief Get the count of glyphs. 90 * 91 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 92 * @param line Indicates the pointer to an <b>OH_Drawing_TextLine</b> object. 93 * @return Returns the count of glyphs. 94 * @since 14 95 * @version 1.0 96 */ 97 double OH_Drawing_TextLineGetGlyphCount(OH_Drawing_TextLine* line); 98 99 /** 100 * @brief Get the range of text line. 101 * 102 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 103 * @param line Indicates the pointer to an <b>OH_Drawing_TextLine</b> object. 104 * @param start Indicates the pointer to text line start position. 105 * @param end Indicates the pointer to text line end position. 106 * @since 14 107 * @version 1.0 108 */ 109 void OH_Drawing_TextLineGetTextRange(OH_Drawing_TextLine* line, size_t* start, size_t* end); 110 111 /** 112 * @brief Get the glyph runs array of text line. 113 * 114 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 115 * @param line Indicates the pointer to an <b>OH_Drawing_TextLine</b> object. 116 * @return Indicates the pointer to a glyph runs array object of text line <b>OH_Drawing_Array</b>. 117 * @since 14 118 * @version 1.0 119 */ 120 OH_Drawing_Array* OH_Drawing_TextLineGetGlyphRuns(OH_Drawing_TextLine* line); 121 122 /** 123 * @brief Releases the memory occupied by the run array object <b>OH_Drawing_Array</b>. 124 * 125 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 126 * @param runs Indicates the pointer to the run array object <b>OH_Drawing_Array</b>. 127 * @since 14 128 * @version 1.0 129 */ 130 void OH_Drawing_DestroyRuns(OH_Drawing_Array* runs); 131 132 /** 133 * @brief Get the run object by index. 134 * 135 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 136 * @param runs Indicates the pointer to the run array object <b>OH_Drawing_Array</b>. 137 * @param index The run object index. 138 * @return Indicates the pointer to a run object <b>OH_Drawing_Run</b>. 139 * @since 14 140 */ 141 OH_Drawing_Run* OH_Drawing_GetRunByIndex(OH_Drawing_Array* runs, size_t index); 142 143 /** 144 * @brief Paint the range of text line. 145 * 146 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 147 * @param line Indicates the pointer to an <b>OH_Drawing_TextLine</b> object. 148 * @param canvas Indicates the pointer to an <b>OH_Drawing_Canvas</b> object. 149 * @param x Represents the X-axis position on the canvas. 150 * @param y Represents the Y-axis position on the canvas. 151 * @since 14 152 * @version 1.0 153 */ 154 void OH_Drawing_TextLinePaint(OH_Drawing_TextLine* line, OH_Drawing_Canvas* canvas, double x, double y); 155 156 /** 157 * @brief Creates a truncated text line object. 158 * 159 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 160 * @param line Indicates the pointer to an <b>OH_Drawing_TextLine</b> object. 161 * @param width Indicates the text line width to set. 162 * @param mode Indicates the ellipsis model to set, EllipsisMode:MIDDLE is not supported. 163 * For details, see the enum <b>OH_Drawing_EllipsisModal</b>. 164 * @param ellipsis Indicates the ellipsis string to set. 165 * @return Returns the pointer to the <b>OH_Drawing_TextLine</b> object created. 166 * @since 14 167 * @version 1.0 168 */ 169 OH_Drawing_TextLine* OH_Drawing_TextLineCreateTruncatedLine(OH_Drawing_TextLine* line, double width, int mode, 170 const char* ellipsis); 171 172 /** 173 * @brief Gets the text line typographic bounds. 174 * 175 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 176 * @param line Indicates the pointer to an <b>OH_Drawing_TextLine</b> object. 177 * @param ascent Indicates the distance that the pointer points to remain above the baseline. 178 * @param descent Indicates the pointer to the distance that remains below the baseline. 179 * @param leading Indicates the pointer to the line Spacing. 180 * @return Returns The total width of the typesetting border. 181 * @since 14 182 * @version 1.0 183 */ 184 double OH_Drawing_TextLineGetTypographicBounds(OH_Drawing_TextLine* line, double* ascent, double* descent, 185 double* leading); 186 187 /** 188 * @brief Gets the text line image bounds. 189 * 190 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 191 * @param line Indicates the pointer to an <b>OH_Drawing_TextLine</b> object. 192 * @return Returns the pointer to the <b>OH_Drawing_Rect</b> struct created. 193 * @since 14 194 * @version 1.0 195 */ 196 OH_Drawing_Rect* OH_Drawing_TextLineGetImageBounds(OH_Drawing_TextLine* line); 197 198 /** 199 * @brief Gets the tail space width. 200 * 201 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 202 * @param line Indicates the pointer to an <b>OH_Drawing_TextLine</b> object. 203 * @return Returns the tail space width. 204 * @since 14 205 * @version 1.0 206 */ 207 double OH_Drawing_TextLineGetTrailingSpaceWidth(OH_Drawing_TextLine* line); 208 209 /** 210 * @brief Gets the string index of the given position. 211 * 212 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 213 * @param line Indicates the pointer to an <b>OH_Drawing_TextLine</b> object. 214 * @param point Indicates the pointer to an <b>OH_Drawing_Point</b> object. 215 * @return Returns the string index for a given position. 216 * @since 14 217 */ 218 int32_t OH_Drawing_TextLineGetStringIndexForPosition(OH_Drawing_TextLine* line, OH_Drawing_Point* point); 219 220 /** 221 * @brief Gets the offset of the given string index. 222 * 223 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 224 * @param line Indicates the pointer to an <b>OH_Drawing_TextLine</b> object. 225 * @param index The given string index. 226 * @return Returns the offset for a given string index. 227 * @since 14 228 */ 229 double OH_Drawing_TextLineGetOffsetForStringIndex(OH_Drawing_TextLine* line, int32_t index); 230 231 /** 232 * @brief User-defined callback functions for using offsets and indexes. 233 * 234 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 235 * @param offset Character offset is traversed as an argument to the callback function. 236 * @param index Character index is traversed as an argument to the callback function. 237 * @param leadingEdge Whether the current offset is at the character front, as an argument to the callback function. 238 * @return The return value of the user-defined callback function. 239 * If false is returned, the traversal continues. 240 * If true is returned, the traversal stops. 241 * @since 14 242 * @version 1.0 243 */ 244 typedef bool (*Drawing_CaretOffsetsCallback)(double offset, int32_t index, bool leadingEdge); 245 246 /** 247 * @brief Enumerate caret offset and index in text lines. 248 * 249 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 250 * @param line Indicates the pointer to an <b>OH_Drawing_TextLine</b> object. 251 * @param callback User-defined callback functions, see <b>Drawing_CaretOffsetsCallback</b>. 252 * @since 14 253 */ 254 void OH_Drawing_TextLineEnumerateCaretOffsets(OH_Drawing_TextLine* line, Drawing_CaretOffsetsCallback callback); 255 256 /** 257 * @brief Gets the text offset based on the given alignment factor and alignment width. 258 * 259 * @syscap SystemCapability.Graphic.Graphic2D.NativeDrawing 260 * @param line Indicates the pointer to an <b>OH_Drawing_TextLine</b> object. 261 * @param alignmentFactor The coefficients that text needs to be aligned. 262 * Less than or equal to 0 is left justified, 0.5 is center justified, 263 * and greater than or equal to 1 is right justified. 264 * @param alignmentWidth The width of the text to be aligned. 265 * Returns 0 if it is less than the actual width of the text. 266 * @return Returns the offset of the aligned text. 267 * @since 14 268 * @version 1.0 269 */ 270 double OH_Drawing_TextLineGetAlignmentOffset(OH_Drawing_TextLine* line, double alignmentFactor, double alignmentWidth); 271 272 #ifdef __cplusplus 273 } 274 #endif 275 /** @} */ 276 #endif // C_INCLUDE_DRAWING_TEXT_LINE_H