1# drawing_text_blob.h 2 3## 概述 4 5文件中定义了与文字相关的功能函数。 6 7**引用文件：** <native_drawing/drawing_text_blob.h> 8 9**库：** libnative_drawing.so 10 11**起始版本：** 11 12 13**相关模块：** [Drawing](capi-drawing.md) 14 15## 汇总 16 17### 结构体 18 19| 名称 | typedef关键字 | 描述 | 20| -- | -- | -- | 21| [OH_Drawing_RunBuffer](capi-drawing-oh-drawing-runbuffer.md) | OH_Drawing_RunBuffer | 结构体用于描述一块内存，描述文字和位置信息。 | 22 23### 函数 24 25| 名称 | 描述 | 26| -- | -- | 27| [OH_Drawing_TextBlobBuilder* OH_Drawing_TextBlobBuilderCreate(void)](#oh_drawing_textblobbuildercreate) | 用于创建一个文本构造器对象。 | 28| [OH_Drawing_TextBlob* OH_Drawing_TextBlobCreateFromText(const void* text, size_t byteLength,const OH_Drawing_Font* font, OH_Drawing_TextEncoding textEncoding)](#oh_drawing_textblobcreatefromtext) | 使用文本创建一个文本对象。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>text、font任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER；<br>textEncoding不在枚举范围内返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。 | 29| [OH_Drawing_TextBlob* OH_Drawing_TextBlobCreateFromPosText(const void* text, size_t byteLength,OH_Drawing_Point2D* point2D, const OH_Drawing_Font* font, OH_Drawing_TextEncoding textEncoding)](#oh_drawing_textblobcreatefrompostext) | 使用文本创建文本对象，文本对象中每个字符的坐标由OH_Drawing_Point2D数组中对应的坐标信息决定。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>text、point2D、font任意一个为NULL或byteLength等于0时返回OH_DRAWING_ERROR_INVALID_PARAMETER；<br>textEncoding不在枚举范围内返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。 | 30| [OH_Drawing_TextBlob* OH_Drawing_TextBlobCreateFromString(const char* str,const OH_Drawing_Font* font, OH_Drawing_TextEncoding textEncoding)](#oh_drawing_textblobcreatefromstring) | 使用字符串创建文本对象。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>str、font任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER；<br>textEncoding不在枚举范围内返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。 | 31| [void OH_Drawing_TextBlobGetBounds(OH_Drawing_TextBlob* textBlob, OH_Drawing_Rect* rect)](#oh_drawing_textblobgetbounds) | 获取文本对象的边界范围。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>textBlob、rect任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 | 32| [uint32_t OH_Drawing_TextBlobUniqueID(const OH_Drawing_TextBlob* textBlob)](#oh_drawing_textblobuniqueid) | 获取文本的标识符，该标识符是唯一的非零值。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>textBlob为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 | 33| [const OH_Drawing_RunBuffer* OH_Drawing_TextBlobBuilderAllocRunPos(OH_Drawing_TextBlobBuilder* textBlobBuilder,const OH_Drawing_Font* font, int32_t count, const OH_Drawing_Rect* rect)](#oh_drawing_textblobbuilderallocrunpos) | 申请一块内存，用于存储文字和位置信息。返回的指针无需调用者管理，当调用[OH_Drawing_TextBlobBuilderMake](capi-drawing-text-blob-h.md#oh_drawing_textblobbuildermake)后禁止使用。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>textBlobBuilder、font任意一个为NULL或者count小于等于0时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 | 34| [OH_Drawing_TextBlob* OH_Drawing_TextBlobBuilderMake(OH_Drawing_TextBlobBuilder* textBlobBuilder)](#oh_drawing_textblobbuildermake) | 用于从文本构造器中创建文本对象。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>textBlobBuilder为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 | 35| [void OH_Drawing_TextBlobDestroy(OH_Drawing_TextBlob* textBlob)](#oh_drawing_textblobdestroy) | 用于销毁文本对象并回收该对象占有的内存。 | 36| [void OH_Drawing_TextBlobBuilderDestroy(OH_Drawing_TextBlobBuilder* textBlobBuilder)](#oh_drawing_textblobbuilderdestroy) | 用于销毁文本构造器对象并回收该对象占有的内存。 | 37 38## 函数说明 39 40### OH_Drawing_TextBlobBuilderCreate() 41 42``` 43OH_Drawing_TextBlobBuilder* OH_Drawing_TextBlobBuilderCreate(void) 44``` 45 46**描述** 47 48用于创建一个文本构造器对象。 49 50**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 51 52**起始版本：** 11 53 54**返回：** 55 56| 类型 | 说明 | 57| -- | -- | 58| [OH_Drawing_TextBlobBuilder](capi-drawing-oh-drawing-textblobbuilder.md)* | 函数会返回一个指针，指针指向创建的文本构造器对象。 | 59 60### OH_Drawing_TextBlobCreateFromText() 61 62``` 63OH_Drawing_TextBlob* OH_Drawing_TextBlobCreateFromText(const void* text, size_t byteLength,const OH_Drawing_Font* font, OH_Drawing_TextEncoding textEncoding) 64``` 65 66**描述** 67 68使用文本创建一个文本对象。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>text、font任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER；<br>textEncoding不在枚举范围内返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。 69 70**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 71 72**起始版本：** 12 73 74 75**参数：** 76 77| 参数项 | 描述 | 78| -- | -- | 79| const void* text | 指向文本的指针。 | 80| size_t byteLength | 文本的字节长度。 | 81| const [OH_Drawing_Font](capi-drawing-oh-drawing-font.md)* font | 指向字体对象[OH_Drawing_Font](capi-drawing-oh-drawing-font.md)的指针。 | 82| [OH_Drawing_TextEncoding](capi-drawing-types-h.md#oh_drawing_textencoding) textEncoding | 文本编码类型[OH_Drawing_TextEncoding](capi-drawing-types-h.md#oh_drawing_textencoding)。 | 83 84**返回：** 85 86| 类型 | 说明 | 87| -- | -- | 88| [OH_Drawing_TextBlob](capi-drawing-oh-drawing-textblob.md)* | 函数返回一个指针，指针指向创建的文本对象[OH_Drawing_TextBlob](capi-drawing-oh-drawing-textblob.md)。 | 89 90### OH_Drawing_TextBlobCreateFromPosText() 91 92``` 93OH_Drawing_TextBlob* OH_Drawing_TextBlobCreateFromPosText(const void* text, size_t byteLength,OH_Drawing_Point2D* point2D, const OH_Drawing_Font* font, OH_Drawing_TextEncoding textEncoding) 94``` 95 96**描述** 97 98使用文本创建文本对象，文本对象中每个字符的坐标由OH_Drawing_Point2D数组中对应的坐标信息决定。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>text、point2D、font任意一个为NULL或byteLength等于0时返回OH_DRAWING_ERROR_INVALID_PARAMETER；<br>textEncoding不在枚举范围内返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。 99 100**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 101 102**起始版本：** 12 103 104 105**参数：** 106 107| 参数项 | 描述 | 108| -- | -- | 109| const void* text | 指向文本的指针。 | 110| size_t byteLength | 文本的字节长度。 | 111| [OH_Drawing_Point2D](capi-drawing-oh-drawing-point2d.md)* point2D | 二维点[OH_Drawing_Point2D](capi-drawing-oh-drawing-point2d.md)数组首地址，数组个数由[OH_Drawing_FontCountText](capi-drawing-font-h.md#oh_drawing_fontcounttext)计算结果决定。 | 112| const [OH_Drawing_Font](capi-drawing-oh-drawing-font.md)* font | 指向字体对象[OH_Drawing_Font](capi-drawing-oh-drawing-font.md)的指针。 | 113| [OH_Drawing_TextEncoding](capi-drawing-types-h.md#oh_drawing_textencoding) textEncoding | 文本编码类型[OH_Drawing_TextEncoding](capi-drawing-types-h.md#oh_drawing_textencoding)。 | 114 115**返回：** 116 117| 类型 | 说明 | 118| -- | -- | 119| [OH_Drawing_TextBlob](capi-drawing-oh-drawing-textblob.md)* | 函数返回一个指针，指针指向创建的文本对象[OH_Drawing_TextBlob](capi-drawing-oh-drawing-textblob.md)。 | 120 121### OH_Drawing_TextBlobCreateFromString() 122 123``` 124OH_Drawing_TextBlob* OH_Drawing_TextBlobCreateFromString(const char* str,const OH_Drawing_Font* font, OH_Drawing_TextEncoding textEncoding) 125``` 126 127**描述** 128 129使用字符串创建文本对象。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>str、font任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER；<br>textEncoding不在枚举范围内返回OH_DRAWING_ERROR_PARAMETER_OUT_OF_RANGE。 130 131**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 132 133**起始版本：** 12 134 135 136**参数：** 137 138| 参数项 | 描述 | 139| -- | -- | 140| const char* str | 指向字符串的指针。 | 141| const [OH_Drawing_Font](capi-drawing-oh-drawing-font.md)* font | 指向字体对象[OH_Drawing_Font](capi-drawing-oh-drawing-font.md)的指针。 | 142| [OH_Drawing_TextEncoding](capi-drawing-types-h.md#oh_drawing_textencoding) textEncoding | 文本编码类型[OH_Drawing_TextEncoding](capi-drawing-types-h.md#oh_drawing_textencoding)。 | 143 144**返回：** 145 146| 类型 | 说明 | 147| -- | -- | 148| [OH_Drawing_TextBlob](capi-drawing-oh-drawing-textblob.md)* | 函数返回一个指针，指针指向创建的文本对象[OH_Drawing_TextBlob](capi-drawing-oh-drawing-textblob.md)。 | 149 150### OH_Drawing_TextBlobGetBounds() 151 152``` 153void OH_Drawing_TextBlobGetBounds(OH_Drawing_TextBlob* textBlob, OH_Drawing_Rect* rect) 154``` 155 156**描述** 157 158获取文本对象的边界范围。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>textBlob、rect任意一个为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 159 160**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 161 162**起始版本：** 12 163 164 165**参数：** 166 167| 参数项 | 描述 | 168| -- | -- | 169| [OH_Drawing_TextBlob](capi-drawing-oh-drawing-textblob.md)* textBlob | 指向文本对象[OH_Drawing_TextBlob](capi-drawing-oh-drawing-textblob.md)的指针。 | 170| [OH_Drawing_Rect](capi-drawing-oh-drawing-rect.md)* rect | 指向矩形对象[OH_Drawing_Rect](capi-drawing-oh-drawing-rect.md)的指针，开发者可调用[OH_Drawing_Rect](capi-drawing-oh-drawing-rect.md)接口创建。 | 171 172### OH_Drawing_TextBlobUniqueID() 173 174``` 175uint32_t OH_Drawing_TextBlobUniqueID(const OH_Drawing_TextBlob* textBlob) 176``` 177 178**描述** 179 180获取文本的标识符，该标识符是唯一的非零值。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>textBlob为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 181 182**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 183 184**起始版本：** 12 185 186 187**参数：** 188 189| 参数项 | 描述 | 190| -- | -- | 191| const [OH_Drawing_TextBlob](capi-drawing-oh-drawing-textblob.md)* textBlob | 指向文本对象[OH_Drawing_TextBlob](capi-drawing-oh-drawing-textblob.md)的指针。 | 192 193**返回：** 194 195| 类型 | 说明 | 196| -- | -- | 197| uint32_t | 返回文本对象的标识符。 | 198 199### OH_Drawing_TextBlobBuilderAllocRunPos() 200 201``` 202const OH_Drawing_RunBuffer* OH_Drawing_TextBlobBuilderAllocRunPos(OH_Drawing_TextBlobBuilder* textBlobBuilder,const OH_Drawing_Font* font, int32_t count, const OH_Drawing_Rect* rect) 203``` 204 205**描述** 206 207申请一块内存，用于存储文字和位置信息。返回的指针无需调用者管理，当调用[OH_Drawing_TextBlobBuilderMake](capi-drawing-text-blob-h.md#oh_drawing_textblobbuildermake)后禁止使用。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>textBlobBuilder、font任意一个为NULL或者count小于等于0时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 208 209**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 210 211**起始版本：** 11 212 213 214**参数：** 215 216| 参数项 | 描述 | 217| -- | -- | 218| [OH_Drawing_TextBlobBuilder](capi-drawing-oh-drawing-textblobbuilder.md)* textBlobBuilder | 指向文本构造器对象的指针。 | 219| const [OH_Drawing_Font](capi-drawing-oh-drawing-font.md)* font | 指向字体对象的指针。 | 220| int32_t count | 文字的数量。 | 221| const [OH_Drawing_Rect](capi-drawing-oh-drawing-rect.md)* rect | 文本的边界框，为NULL表示不设置边界框。 | 222 223### OH_Drawing_TextBlobBuilderMake() 224 225``` 226OH_Drawing_TextBlob* OH_Drawing_TextBlobBuilderMake(OH_Drawing_TextBlobBuilder* textBlobBuilder) 227``` 228 229**描述** 230 231用于从文本构造器中创建文本对象。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>textBlobBuilder为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 232 233**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 234 235**起始版本：** 11 236 237 238**参数：** 239 240| 参数项 | 描述 | 241| -- | -- | 242| [OH_Drawing_TextBlobBuilder](capi-drawing-oh-drawing-textblobbuilder.md)* textBlobBuilder | 指向文本构造器对象的指针。 | 243 244**返回：** 245 246| 类型 | 说明 | 247| -- | -- | 248| [OH_Drawing_TextBlob](capi-drawing-oh-drawing-textblob.md)* | 返回一个指针，指针指向创建的文本对象。 | 249 250### OH_Drawing_TextBlobDestroy() 251 252``` 253void OH_Drawing_TextBlobDestroy(OH_Drawing_TextBlob* textBlob) 254``` 255 256**描述** 257 258用于销毁文本对象并回收该对象占有的内存。 259 260**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 261 262**起始版本：** 11 263 264 265**参数：** 266 267| 参数项 | 描述 | 268| -- | -- | 269| [OH_Drawing_TextBlob](capi-drawing-oh-drawing-textblob.md)* textBlob | 指向文本对象的指针。 | 270 271### OH_Drawing_TextBlobBuilderDestroy() 272 273``` 274void OH_Drawing_TextBlobBuilderDestroy(OH_Drawing_TextBlobBuilder* textBlobBuilder) 275``` 276 277**描述** 278 279用于销毁文本构造器对象并回收该对象占有的内存。 280 281**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 282 283**起始版本：** 11 284 285 286**参数：** 287 288| 参数项 | 描述 | 289| -- | -- | 290| [OH_Drawing_TextBlobBuilder](capi-drawing-oh-drawing-textblobbuilder.md)* textBlobBuilder | 指向文本构造器对象的指针。 | 291 292 293