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 ArkUI_NativeModule
18 * @{
19 *
20 * @brief Provides ArkUI UI capabilities on the Native side, such as UI component creation and destruction,
21 * tree node operation, property setting, event monitoring, and so on.
22 *
23 * @since 12
24 */
25
26/**
27 * @file styled_string.h
28 *
29 * @brief Provides ArkUI with property string capabilities on the Native side.
30 *
31 * @library libace_ndk.z.so
32 * @syscap SystemCapability.ArkUI.ArkUI.Full
33 * @kit ArkUI
34 * @since 12
35 */
36
37#ifndef ARKUI_NATIVE_STYLED_STRING_H
38#define ARKUI_NATIVE_STYLED_STRING_H
39
40#include "native_drawing/drawing_text_declaration.h"
41#include "native_drawing/drawing_text_typography.h"
42#include "native_type.h"
43
44#ifdef __cplusplus
45extern "C" {
46#endif
47
48/**
49 * @brief Defines formatted string data objects supported by the text component.
50 *
51 * @since 12
52 */
53typedef struct ArkUI_StyledString ArkUI_StyledString;
54
55/**
56 * @brief Creates a pointer to the ArkUI_StyledString object.
57 *
58 * @param style A pointer to OH_Drawing_TypographyStyle, obtained by {@link OH_Drawing_CreateTypographyStyle}.
59 * @param collection A pointer to OH_Drawing_FontCollection, obtained by {@link OH_Drawing_CreateFontCollection}.
60 * @return Creates a pointer to the ArkUI_StyledString object. If the object returns a null pointer,
61 *         the creation failed, either because the address space was full,
62 *         or because the style, collection parameter was an exception such as a null pointer.
63 * @since 12
64 */
65ArkUI_StyledString* OH_ArkUI_StyledString_Create(
66    OH_Drawing_TypographyStyle* style, OH_Drawing_FontCollection* collection);
67
68/**
69 * @brief Free the memory occupied by the ArkUI_StyledString object.
70 *
71 * @param handle A pointer to the ArkUI_StyledString object.
72 * @since 12
73 */
74void OH_ArkUI_StyledString_Destroy(ArkUI_StyledString* handle);
75
76/**
77 * @brief Sets the new layout style to the top of the current format string style stack.
78 *
79 * @param handle A pointer to the ArkUI_StyledString object.
80 * @param style A pointer to the OH_Drawing_TextStyle object.
81 * @since 12
82 */
83void OH_ArkUI_StyledString_PushTextStyle(ArkUI_StyledString* handle, OH_Drawing_TextStyle* style);
84
85/**
86 * @brief Sets the corresponding text content based on the current format string style.
87 *
88 * @param handle A pointer to the ArkUI_StyledString object.
89 * @param content A pointer to the text content.
90 * @since 12
91 */
92void OH_ArkUI_StyledString_AddText(ArkUI_StyledString* handle, const char* content);
93
94/**
95 * @brief Removes the top style from the stack in the current format string object.
96 *
97 * @param handle A pointer to the ArkUI_StyledString object.
98 * @since 12
99 */
100void OH_ArkUI_StyledString_PopTextStyle(ArkUI_StyledString* handle);
101
102/**
103 * @brief Creates a pointer to an OH_Drawing_Typography object based on a format string object
104 * for advanced text estimation and typography.
105 *
106 * @param handle A pointer to the ArkUI_StyledString object.
107 * @return A pointer to the OH_Drawing_Typography object. If the object returns a null pointer,
108 *         the creation fails because the handle parameter is abnormal, such as a null pointer.
109 * @since 12
110 */
111OH_Drawing_Typography* OH_ArkUI_StyledString_CreateTypography(ArkUI_StyledString* handle);
112
113/**
114 * @brief Set the placeholder.
115 *
116 * @param handle A pointer to the ArkUI_StyledString object.
117 * @param placeholder A pointer to the OH_Drawing_PlaceholderSpan object.
118 * @since 12
119 */
120void OH_ArkUI_StyledString_AddPlaceholder(ArkUI_StyledString* handle, OH_Drawing_PlaceholderSpan* placeholder);
121
122/**
123 * @brief Create a ArkUI_StyledString_Descriptor object.
124 *
125 * @return Pointer to the ArkUI_StyledString_Descriptor object.。
126 * @since 14
127 */
128ArkUI_StyledString_Descriptor* OH_ArkUI_StyledString_Descriptor_Create();
129
130/**
131 * @brief Release the memory occupied by the ArkUI_StyledString_Descriptor object.
132 *
133 * @param str Pointer to the ArkUI_StyledString_Descriptor object.
134 * @since 14
135 */
136void OH_ArkUI_StyledString_Descriptor_Destroy(ArkUI_StyledString_Descriptor* str);
137
138/**
139 * @brief Convert the styled string into html.
140 *
141 * @param str Pointer to the ArkUI_StyledString_Descriptor object.
142 * @return The converted html.
143 * @since 14
144 */
145const char* OH_ArkUI_ConvertToHtml(ArkUI_StyledString_Descriptor* str);
146
147/**
148 * @brief Deserializes a byte array containing styled string information into a styled string.
149 *
150 * @param buffer Byte array to be deserialized.
151 * @param bufferSize Length of the byte array.
152 * @param descriptor Pointer to an <b>ArkUI_StyledString_Descriptor</b> object.
153 * @return Returns the result code.
154 *         Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful.
155 *         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs.
156 * @since 14
157 */
158int32_t OH_ArkUI_UnmarshallStyledStringDescriptor(
159    uint8_t* buffer, size_t bufferSize, ArkUI_StyledString_Descriptor* descriptor);
160
161/**
162 * @brief Serializes the styled string information into a byte array.
163 *
164 * @param buffer Byte array where the serialized data will be stored.
165 * @param bufferSize Length of the byte array.
166 * @param descriptor Pointer to an <b>ArkUI_StyledString_Descriptor</b> object.
167 * @param resultSize Actual length of the byte array.
168 * @return Returns the result code.
169 *         Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful.
170 *         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs.
171 *         Returns {@link ARKUI_ERROR_CODE_INVALID_STYLED_STRING} if the styled string is invalid.
172 * @since 14
173 */
174int32_t OH_ArkUI_MarshallStyledStringDescriptor(
175    uint8_t* buffer, size_t bufferSize, ArkUI_StyledString_Descriptor* descriptor, size_t* resultSize);
176
177#ifdef __cplusplus
178};
179#endif
180
181#endif // ARKUI_NATIVE_STYLED_STRING_H
182/** @} */
183