# Drawing and Displaying Text in Text Components
Some frameworks or applications have their own text layout capabilities, which are integrated into the ArkGraphics2D text engine during porting. To avoid the need for redeveloping text components, the **Text** component provides the [NODE_TEXT_CONTENT_WITH_STYLED_STRING](../../application-dev/reference/apis-arkui/_ark_u_i___native_module.md) API, which can directly render text generated by the Ark text engine.

The following, based on the [Integrating with ArkTS Pages](../ui/ndk-access-the-arkts-page.md) section, explains how to create text engine text and use the **Text** component for rendering and display.

> **NOTE**
>
> For APIs involving the font engine, add **target_link_libraries(entry PUBLIC libnative_drawing.so)** to **CMakeLists.txt**; otherwise, a linking error will occur.

## Creating a Text Component

Since text styles are set through font engine APIs, there is no need to configure style attributes such as text color and font size when creating a **Text** component. However, basic universal attributes such as width and height still need to be set.
```c++
ArkUI_NativeNodeAPI_1 *nodeApi = reinterpret_cast<ArkUI_NativeNodeAPI_1 *>(
    OH_ArkUI_QueryModuleInterfaceByName(ARKUI_NATIVE_NODE, "ArkUI_NativeNodeAPI_1"));
if (nodeApi == nullptr) {
    return;
}
ArkUI_NodeHandle text = nodeApi->createNode(ARKUI_NODE_TEXT);
// Set the width.
ArkUI_NumberValue textWidth[] = {{.f32 = 300}};
ArkUI_AttributeItem textWidthItem = {.value = textWidth, .size = 1};
nodeApi->setAttribute(text, NODE_WIDTH, &textWidthItem);
// Set the height.
ArkUI_NumberValue textHeight[] = {{.f32 = 100}};
ArkUI_AttributeItem textHeightItem = {.value = textHeight, .size = 1};
nodeApi->setAttribute(text, NODE_HEIGHT, &textHeightItem);
```
## Setting Paragraph and Text Styles

- Setting the Paragraph Style

    The paragraph style defines the overall attributes of a paragraph of text, such as the maximum number of display lines and text direction. The following code example sets text centering and a maximum line limit of 10.
    
    > **NOTE**
    > 
    > The **OH_Drawing_** prefixed APIs are provided by the Ark text engine.
    ```c++
    OH_Drawing_TypographyStyle *typographyStyle = OH_Drawing_CreateTypographyStyle();
    OH_Drawing_SetTypographyTextAlign(typographyStyle, OH_Drawing_TextAlign::TEXT_ALIGN_CENTER);
    OH_Drawing_SetTypographyTextMaxLines(typographyStyle, 10);
    ```
- Setting the Text Style

    Different text contents can have different text styles, but the following three APIs must be called in the specified order; otherwise, they will not take effect.

    1. **OH_ArkUI_StyledString_PushTextStyle**: pushes the text style onto the stack.
    2. **OH_ArkUI_StyledString_AddText**: adds the text content to which the style will be applied.
    3. **OH_ArkUI_StyledString_PopTextStyle**: pops the text style from the stack.

    > **NOTE**
    > 
    > The **OH_ArkUI_StyledString_** prefixed APIs are provided by the **Text** component.
    >
    > The **OH_Drawing_** prefixed APIs are provided by the Ark text engine.

    Create a text style with **OH_Drawing_CreateTextStyle**. Set the font size of **"Hello"** to 28 px and the color to **0xFF707070**. Set the font size of **"World!"** to 28 px and the color to **0xFF2787D9**.
    ```c++
    ArkUI_StyledString *styledString = OH_ArkUI_StyledString_Create(typographyStyle,OH_Drawing_CreateFontCollection());

    OH_Drawing_TextStyle *helloStyle = OH_Drawing_CreateTextStyle();
    // Set the font size.
    OH_Drawing_SetTextStyleFontSize(helloStyle, 28);
    // Set the color
    OH_Drawing_SetTextStyleColor(helloStyle, OH_Drawing_ColorSetArgb(0xFF, 0x70, 0x70, 0x70));
    OH_ArkUI_StyledString_PushTextStyle(styledString, helloStyle);
    OH_ArkUI_StyledString_AddText(styledString, "Hello");
    OH_ArkUI_StyledString_PopTextStyle(styledString);

    OH_Drawing_TextStyle *worldTextStyle = OH_Drawing_CreateTextStyle();
    OH_Drawing_SetTextStyleFontSize(worldTextStyle, 28);
    OH_Drawing_SetTextStyleColor(worldTextStyle, OH_Drawing_ColorSetArgb(0xFF, 0x27,0x87, 0xD9));
    OH_ArkUI_StyledString_PushTextStyle(styledString, worldTextStyle);
    OH_ArkUI_StyledString_AddText(styledString, "World!");
    OH_ArkUI_StyledString_PopTextStyle(styledString);
    ```
## Adding a Placeholder
A placeholder reserves a blank area of a specified size in the middle of text. No text is drawn in this area, but it still participates in text layout measurement. Therefore, its size affects text typesetting.
> **NOTE**
> 
> The relative position of the placeholder and text is determined by the execution order of **OH_ArkUI_StyledString_AddPlaceholder**.

```c++
OH_Drawing_PlaceholderSpan placeHolder{
    .width = 100,
    .height = 100,
};
OH_ArkUI_StyledString_AddPlaceholder(styledString, placeHolder);
```
## Implementing Text Layout and Drawing
- Text Layout

    After setting the text style and content, call the text engine API **OH_Drawing_TypographyLayout** to lay out the text, and pass in a specified width representing the maximum value for the text.
    
    > **NOTE**
    >
    > Text that has not been laid out is not displayed.

    ```c++
    OH_Drawing_Typography *typography = OH_ArkUI_StyledString_CreateTypography(styledString);
    OH_Drawing_TypographyLayout(typography, 400);
    ```

- Text Drawing

    Text drawing is completed through interaction between the text engine and graphics, requiring no additional settings. The **Text** component will call the text engine drawing API when the component triggers drawing under the ArkUI rendering mechanism. Here, only the created **StyledString** object needs to be passed to the created **Text** component.
    ```c++
    ArkUI_AttributeItem styledStringItem = {.object = styledString};
    nodeApi->setAttribute(text, NODE_TEXT_CONTENT_WITH_STYLED_STRING, &styledStringItem);
    ```

## Destroying an Object

The **Text** component does not manage the lifecycle of any objects involved in this process. You are responsible for this.  

The text engine APIs involved all have corresponding destruction methods.

**OH_Drawing_DestroyTextStyle(OH_Drawing_TextStyle *style)**: destroys the text style object.

**OH_Drawing_DestroyTypographyStyle(OH_Drawing_TypographyStyle *style)**: destroys the paragraph style object.

The **Text** component provides **OH_ArkUI_StyledString_Destroy** to destroy the styled string object.

## Sample
```c++
void CreateNativeNode() {
    ArkUI_NativeNodeAPI_1 *nodeApi = reinterpret_cast<ArkUI_NativeNodeAPI_1 *>(
        OH_ArkUI_QueryModuleInterfaceByName(ARKUI_NATIVE_NODE, "ArkUI_NativeNodeAPI_1"));
    if (nodeApi == nullptr) {
        return;
    }
    // Create a Column container component.
    ArkUI_NodeHandle column = nodeApi->createNode(ARKUI_NODE_COLUMN);
    ArkUI_NumberValue colWidth[] = {{.f32 = 300}};
    ArkUI_AttributeItem widthItem = {.value = colWidth, .size = 1};
    nodeApi->setAttribute(column, NODE_WIDTH, &widthItem);
    // Create a Text component.
    ArkUI_NodeHandle text = nodeApi->createNode(ARKUI_NODE_TEXT);
    ArkUI_NumberValue textWidth[] = {{.f32 = 300}};
    ArkUI_AttributeItem textWidthItem = {.value = textWidth, .size = 1};
    nodeApi->setAttribute(text, NODE_WIDTH, &textWidthItem);
    
    ArkUI_NumberValue textHeight[] = {{.f32 = 100}};
    ArkUI_AttributeItem textHeightItem = {.value = textHeight, .size = 1};
    nodeApi->setAttribute(text, NODE_HEIGHT, &textHeightItem);
    
    ArkUI_NumberValue borderWidth[] = {{.f32 = 1}};
    ArkUI_AttributeItem borderWidthItem = {.value = borderWidth, .size = 1};
    nodeApi->setAttribute(text, NODE_BORDER_WIDTH, &borderWidthItem);
    
    // typographyStyle represents the paragraph style.
    OH_Drawing_TypographyStyle *typographyStyle = OH_Drawing_CreateTypographyStyle();
    // Center the text.
    OH_Drawing_SetTypographyTextAlign(typographyStyle, OH_Drawing_TextAlign::TEXT_ALIGN_CENTER);
    OH_Drawing_SetTypographyTextMaxLines(typographyStyle, 10);
    ArkUI_StyledString *styledString = OH_ArkUI_StyledString_Create(typographyStyle, OH_Drawing_CreateFontCollection());
    // Create a text style and set the font and color.
    OH_Drawing_TextStyle *textStyle = OH_Drawing_CreateTextStyle();
    OH_Drawing_SetTextStyleFontSize(textStyle, 28);
    OH_Drawing_SetTextStyleColor(textStyle, OH_Drawing_ColorSetArgb(0xFF, 0x70, 0x70, 0x70));
    // The setting order of text styles matters.
    OH_ArkUI_StyledString_PushTextStyle(styledString, textStyle);
    OH_ArkUI_StyledString_AddText(styledString, "Hello");
    OH_ArkUI_StyledString_PopTextStyle(styledString);
    // Insert a 100 x 100 placeholder between "Hello" and "World!"
    OH_Drawing_PlaceholderSpan placeHolder{
        .width = 100,
        .height = 100,
    };
    OH_ArkUI_StyledString_AddPlaceholder(styledString, &placeHolder);
    OH_Drawing_TextStyle *worldTextStyle = OH_Drawing_CreateTextStyle();
    OH_Drawing_SetTextStyleFontSize(worldTextStyle, 28);
    OH_Drawing_SetTextStyleColor(worldTextStyle, OH_Drawing_ColorSetArgb(0xFF, 0x27, 0x87, 0xD9));
    OH_ArkUI_StyledString_PushTextStyle(styledString, worldTextStyle);
    OH_ArkUI_StyledString_AddText(styledString, "World!");
    OH_ArkUI_StyledString_PopTextStyle(styledString);
    OH_Drawing_Typography *typography = OH_ArkUI_StyledString_CreateTypography(styledString);
    OH_Drawing_TypographyLayout(typography, 400);
    ArkUI_AttributeItem styledStringItem = {.object = styledString};
    nodeApi->setAttribute(text, NODE_TEXT_CONTENT_WITH_STYLED_STRING, &styledStringItem);

    OH_ArkUI_StyledString_Destroy(styledString);
    // Add Text as a child component of Column.
    nodeApi->addChild(column, text);
    // Add Column as a child component of XComponent.
    OH_NativeXComponent_AttachNativeRootNode(xComponent, column);
}
```

![ndk_text_styled_string](figures/ndk_text_styled_string.png)
<!--no_check-->