styled_string.h
Overview
Defines the text style and layout manager for the component whose type is set to ARKUI_NODE_TEXT on the native side.
File to include: <arkui/styled_string.h>
Library: libace_ndk.z.so
System capability: SystemCapability.ArkUI.ArkUI.Full
Since: 12
Related module: ArkUI_NativeModule
Sample: StyledStringSample
Summary
Structs
| Name | typedef Keyword | Description |
|---|---|---|
| ArkUI_StyledString | ArkUI_StyledString | Defines a styled string object supported by the text component. |
| ArkUI_TextLayoutManager | ArkUI_TextLayoutManager | Defines a text layout manager. |
Functions
Function Description
OH_ArkUI_StyledString_Create()
ArkUI_StyledString* OH_ArkUI_StyledString_Create(OH_Drawing_TypographyStyle* style, OH_Drawing_FontCollection* collection)
Description
Creates a pointer to the ArkUI_StyledString object.
Since: 12
Parameters
| Name | Description |
|---|---|
| OH_Drawing_TypographyStyle* style | Pointer to an OH_Drawing_TypographyStyle object, obtained using OH_Drawing_CreateTypographyStyle. |
| OH_Drawing_FontCollection* collection | Pointer to an OH_Drawing_FontCollection object, obtained using OH_Drawing_CreateFontCollection. |
Return value
| Type | Description |
|---|---|
| ArkUI_StyledString* | Pointer to the newly created ArkUI_StyledString object. If a null pointer is returned, the creation fails. Possible causes include a full application address space or parameter errors, such as a null pointer being passed for the style or collection parameter. |
OH_ArkUI_StyledString_Destroy()
void OH_ArkUI_StyledString_Destroy(ArkUI_StyledString* handle)
Description
Destroys an ArkUI_StyledString object and reclaims the memory occupied by the object.
Since: 12
Parameters
| Name | Description |
|---|---|
| ArkUI_StyledString* handle | Pointer to an ArkUI_StyledString object. |
OH_ArkUI_StyledString_PushTextStyle()
void OH_ArkUI_StyledString_PushTextStyle(ArkUI_StyledString* handle, OH_Drawing_TextStyle* style)
Description
Pushes a text style to the top of the style stack of a styled string.
Since: 12
Parameters
| Name | Description |
|---|---|
| ArkUI_StyledString* handle | Pointer to an ArkUI_StyledString object. |
| OH_Drawing_TextStyle* style | Pointer to an OH_Drawing_TextStyle object. |
OH_ArkUI_StyledString_AddText()
void OH_ArkUI_StyledString_AddText(ArkUI_StyledString* handle, const char* content)
Description
Adds text for a styled string.
Since: 12
Parameters
| Name | Description |
|---|---|
| ArkUI_StyledString* handle | Pointer to an ArkUI_StyledString object. |
| const char* content | Pointer to the text content. |
OH_ArkUI_StyledString_PopTextStyle()
void OH_ArkUI_StyledString_PopTextStyle(ArkUI_StyledString* handle)
Description
Pops the style at the top of the style stack of a styled string.
Since: 12
Parameters
| Name | Description |
|---|---|
| ArkUI_StyledString* handle | Pointer to an ArkUI_StyledString object. |
OH_ArkUI_StyledString_CreateTypography()
OH_Drawing_Typography* OH_ArkUI_StyledString_CreateTypography(ArkUI_StyledString* handle)
Description
Creates an OH_Drawing_Typography object based on an ArkUI_StyledString object.
Since: 12
Parameters
| Name | Description |
|---|---|
| ArkUI_StyledString* handle | Pointer to an ArkUI_StyledString object. |
Return value
| Type | Description |
|---|---|
| OH_Drawing_Typography* | Pointer to the OH_Drawing_Typography object. If a null pointer is returned, the creation fails. A possible cause is that a parameter error, for example, a null pointer for the handle parameter, occurs. |
OH_ArkUI_StyledString_AddPlaceholder()
void OH_ArkUI_StyledString_AddPlaceholder(ArkUI_StyledString* handle, OH_Drawing_PlaceholderSpan* placeholder)
Description
Adds a placeholder.
Since: 12
Parameters
| Name | Description |
|---|---|
| ArkUI_StyledString* handle | Pointer to an ArkUI_StyledString object. |
| OH_Drawing_PlaceholderSpan* placeholder | Pointer to an OH_Drawing_PlaceholderSpan object. |
OH_ArkUI_StyledString_Descriptor_Create()
ArkUI_StyledString_Descriptor* OH_ArkUI_StyledString_Descriptor_Create(void)
Description
Creates an ArkUI_StyledString_Descriptor object.
Since: 14
Return value
| Type | Description |
|---|---|
| ArkUI_StyledString_Descriptor* | Pointer to an ArkUI_StyledString_Descriptor object. |
OH_ArkUI_StyledString_Descriptor_Destroy()
void OH_ArkUI_StyledString_Descriptor_Destroy(ArkUI_StyledString_Descriptor* descriptor)
Description
Destroys an ArkUI_StyledString_Descriptor object and reclaims the memory occupied by the object.
Since: 14
Parameters
| Name | Description |
|---|---|
| ArkUI_StyledString_Descriptor* descriptor | Pointer to an ArkUI_StyledString_Descriptor object. |
OH_ArkUI_UnmarshallStyledStringDescriptor()
int32_t OH_ArkUI_UnmarshallStyledStringDescriptor(uint8_t* buffer, size_t bufferSize, ArkUI_StyledString_Descriptor* descriptor)
Description
Unmarshals a byte array containing styled string information into a styled string.
Since: 14
Parameters
| Name | Description |
|---|---|
| uint8_t* buffer | Pointer to the byte array to be deserialized. |
| size_t bufferSize | Length of the byte array. |
| ArkUI_StyledString_Descriptor* descriptor | Pointer to an ArkUI_StyledString_Descriptor object. |
Return value
| Type | Description |
|---|---|
| int32_t | Result code. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs. |
OH_ArkUI_MarshallStyledStringDescriptor()
int32_t OH_ArkUI_MarshallStyledStringDescriptor(uint8_t* buffer, size_t bufferSize, ArkUI_StyledString_Descriptor* descriptor, size_t* resultSize)
Description
Marshals the styled string information into a byte array.
Since: 14
Parameters
| Name | Description |
|---|---|
| uint8_t* buffer | Pointer to the byte array where the serialized data will be stored. |
| size_t bufferSize | Length of the byte array. |
| ArkUI_StyledString_Descriptor* descriptor | Pointer to an ArkUI_StyledString_Descriptor object. |
| size_t* resultSize | Pointer to the actual length of the resulting byte array after deserialization. |
Return value
| Type | Description |
|---|---|
| int32_t | Result code. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs. Returns ARKUI_ERROR_CODE_INVALID_STYLED_STRING if the styled string is invalid. |
OH_ArkUI_ConvertToHtml()
const char* OH_ArkUI_ConvertToHtml(ArkUI_StyledString_Descriptor* descriptor)
Description
Converts styled string information into HTML.
Since: 14
Parameters
| Name | Description |
|---|---|
| ArkUI_StyledString_Descriptor* descriptor | Pointer to an ArkUI_StyledString_Descriptor object. |
Return value
| Type | Description |
|---|---|
| const char* | Pointer to the HTML object. This pointer is internally managed and is released when OH_ArkUI_StyledString_Descriptor_Destroy() is called. |
OH_ArkUI_TextLayoutManager_Dispose()
void OH_ArkUI_TextLayoutManager_Dispose(ArkUI_TextLayoutManager* layoutManager)
Description
Releases the memory occupied by the text layout manager.
Since: 22
Parameters
| Name | Description |
|---|---|
| ArkUI_TextLayoutManager* layoutManager | Pointer to the ArkUI_TextLayoutManager object. |
OH_ArkUI_TextLayoutManager_GetLineCount()
ArkUI_ErrorCode OH_ArkUI_TextLayoutManager_GetLineCount(ArkUI_TextLayoutManager* layoutManager, int32_t* outLineCount)
Description
Obtains the number of lines.
Since: 22
Parameters
| Name | Description |
|---|---|
| ArkUI_TextLayoutManager* layoutManager | Pointer to the ArkUI_TextLayoutManager object. |
| int32_t* outLineCount | Pointer to the number of text lines. |
Return value
| Type | Description |
|---|---|
| ArkUI_ErrorCode | Return result. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs. |
OH_ArkUI_TextLayoutManager_GetRectsForRange()
ArkUI_ErrorCode OH_ArkUI_TextLayoutManager_GetRectsForRange(ArkUI_TextLayoutManager* layoutManager, int32_t start, int32_t end, OH_Drawing_RectWidthStyle widthStyle, OH_Drawing_RectHeightStyle heightStyle, OH_Drawing_TextBox** outTextBoxes)
Description
Obtains the drawing area information of characters or placeholders within a specified text range under the given rectangle width and height.
Since: 22
Parameters
| Name | Description |
|---|---|
| ArkUI_TextLayoutManager* layoutManager | Pointer to the ArkUI_TextLayoutManager object. |
| int32_t start | Start index. The value of start must be greater than or equal to 0. Otherwise, a parameter error is returned. |
| int32_t end | End index. The value of end must be greater than or equal to that of start. Otherwise, aparameter error is returned. |
| OH_Drawing_RectWidthStyle widthStyle | Width style of the rectangle. |
| OH_Drawing_RectHeightStyle heightStyle | Height style of the rectangle. |
| OH_Drawing_TextBox** outTextBoxes | Level-2 pointer to the OH_Drawing_TextBox object. |
Return value
| Type | Description |
|---|---|
| ArkUI_ErrorCode | Return result. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs. |
OH_ArkUI_TextLayoutManager_GetGlyphPositionAtCoordinate()
ArkUI_ErrorCode OH_ArkUI_TextLayoutManager_GetGlyphPositionAtCoordinate(ArkUI_TextLayoutManager* layoutManager, double dx, double dy, OH_Drawing_PositionAndAffinity** outPos)
Description
Obtains the position of the glyph closest to the given coordinates.
Since: 22
Parameters
| Name | Description |
|---|---|
| ArkUI_TextLayoutManager* layoutManager | Pointer to the ArkUI_TextLayoutManager object. |
| double dx | X coordinate relative to the control, in px. |
| double dy | Y coordinate relative to the control, in px. |
| OH_Drawing_PositionAndAffinity** outPos | Level-2 pointer to the OH_Drawing_PositionAndAffinity object. |
Return value
| Type | Description |
|---|---|
| ArkUI_ErrorCode | Return result. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs. |
OH_ArkUI_TextLayoutManager_GetLineMetrics()
ArkUI_ErrorCode OH_ArkUI_TextLayoutManager_GetLineMetrics(ArkUI_TextLayoutManager* layoutManager, int32_t lineNumber, OH_Drawing_LineMetrics* outMetrics)
Description
Obtains the information about the specified line, including line metrics, text style information, and font properties.
Since: 22
Parameters
| Name | Description |
|---|---|
| ArkUI_TextLayoutManager* layoutManager | Pointer to the ArkUI_TextLayoutManager object. |
| int32_t lineNumber | Index of the line number. It starts from 0. If the value of lineNumber is less than 0 or greater than or equal to the number of text lines, a parameter error is returned. |
| OH_Drawing_LineMetrics* outMetrics | Pointer to the OH_Drawing_LineMetrics object. |
Return value
| Type | Description |
|---|---|
| ArkUI_ErrorCode | Return result. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs. |
OH_ArkUI_TextLayoutManager_GetCharacterPositionAtCoordinate()
ArkUI_ErrorCode OH_ArkUI_TextLayoutManager_GetCharacterPositionAtCoordinate(ArkUI_TextLayoutManager* layoutManager, double dx, double dy, OH_Drawing_PositionAndAffinity** outPos)
Description
Obtains the position of the character closest to the specified control.
Since: 24
Parameters
| Name | Description |
|---|---|
| ArkUI_TextLayoutManager* layoutManager | Pointer to the ArkUI_TextLayoutManager object. |
| double dx | X coordinate relative to the control, in px. |
| double dy | Y coordinate relative to the control, in px. |
| OH_Drawing_PositionAndAffinity** outPos | Level-2 pointer to the OH_Drawing_PositionAndAffinity object. |
Return value
| Type | Description |
|---|---|
| ArkUI_ErrorCode | Return result. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs. |
OH_ArkUI_TextLayoutManager_GetGlyphRangeForCharacterRange()
ArkUI_ErrorCode OH_ArkUI_TextLayoutManager_GetGlyphRangeForCharacterRange(ArkUI_TextLayoutManager* layoutManager, OH_Drawing_Range* charRange, OH_Drawing_Range** outGlyphRange,
OH_Drawing_Range** outActualCharRange);
Description
Obtains the glyph index range generated by the specified character index range and the actual character index range. If the first glyph is a Chinese character, the glyph index range of the character is [0, 1]. A Chinese character occupies three characters, so the corresponding character index range is [0, 3]. If the specified character index range is [0, 1], one third of a Chinese character cannot be parsed, so the actual character index range is [0, 3].
Since: 24
Parameters
| Name | Description |
|---|---|
| ArkUI_TextLayoutManager* layoutManager | Pointer to the ArkUI_TextLayoutManager object. |
| OH_Drawing_Range* charRange | Pointer to the OH_Drawing_Range object, indicating the character index range. |
| OH_Drawing_Range** outGlyphRange | Level-2 pointer to the OH_Drawing_Range object, indicating the glyph index range. |
| OH_Drawing_Range** outActualCharRange | Level-2 pointer to the OH_Drawing_Range object, indicating the actual character index range. |
Return value
| Type | Description |
|---|---|
| ArkUI_ErrorCode | Return result. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs. |
OH_ArkUI_TextLayoutManager_GetCharacterRangeForGlyphRange()
ArkUI_ErrorCode OH_ArkUI_TextLayoutManager_GetCharacterRangeForGlyphRange(ArkUI_TextLayoutManager* layoutManager, OH_Drawing_Range* glyphRange, OH_Drawing_Range** outCharRange,
OH_Drawing_Range** outActualGlyphRange)
Description
Obtains the character index range generated by the specified glyph index range and the actual glyph index range. If a text contains two Chinese characters and five letters, the glyph index range of the text is [0, 7]. A Chinese character occupies three characters, so the corresponding character index range is [0, 11]. If the specified index range is [0, 11], but there are only seven glyphs, the actual glyph index range is [0, 7].
Since: 24
Parameters
| Name | Description |
|---|---|
| ArkUI_TextLayoutManager* layoutManager | Pointer to the ArkUI_TextLayoutManager object. |
| OH_Drawing_Range* charRange | Pointer to the OH_Drawing_Range object, indicating the glyph index range. |
| OH_Drawing_Range** outGlyphRange | Level-2 pointer to the OH_Drawing_Range object, indicating the character index range. |
| OH_Drawing_Range** outActualCharRange | Level-2 pointer to the OH_Drawing_Range object, indicating the actual glyph index range. |
Return value
| Type | Description |
|---|---|
| ArkUI_ErrorCode | Return result. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs. |