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 45 extern "C" { 46 #endif 47 48 /** 49 * @brief Defines formatted string data objects supported by the text component. 50 * 51 * @since 12 52 */ 53 typedef 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 */ 65 ArkUI_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 */ 74 void 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 */ 83 void 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 */ 92 void 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 */ 100 void 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 */ 111 OH_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 */ 120 void OH_ArkUI_StyledString_AddPlaceholder(ArkUI_StyledString* handle, OH_Drawing_PlaceholderSpan* placeholder); 121 122 /** 123 * @brief Creates an <b>ArkUI_StyledString_Descriptor</b> object. 124 * 125 * @return Returns the pointer to the <b>ArkUI_StyledString_Descriptor</b> object created. 126 * @since 14 127 */ 128 ArkUI_StyledString_Descriptor* OH_ArkUI_StyledString_Descriptor_Create(void); 129 130 /** 131 * @brief Destroys an <b>ArkUI_StyledString_Descriptor</b> object and reclaims the memory occupied by the object. 132 * 133 * @param descriptor Pointer to an <b>ArkUI_StyledString_Descriptor</b> object. 134 * @since 14 135 */ 136 void OH_ArkUI_StyledString_Descriptor_Destroy(ArkUI_StyledString_Descriptor* descriptor); 137 138 /** 139 * @brief Converts styled string information into HTML. 140 * 141 * @param descriptor Pointer to an <b>ArkUI_StyledString_Descriptor</b> object. 142 * @return Returns the pointer to the resulting HTML string. This pointer is managed internally and should be destroyed 143 * by calling <b>OH_ArkUI_StyledString_Descriptor_Destroy()</b> when no longer needed to free the memory. 144 * @since 14 145 */ 146 const char* OH_ArkUI_ConvertToHtml(ArkUI_StyledString_Descriptor* descriptor); 147 148 /** 149 * @brief Deserializes a byte array containing styled string information into a styled string. 150 * 151 * @param buffer Byte array to be deserialized. 152 * @param bufferSize Length of the byte array. 153 * @param descriptor Pointer to an <b>ArkUI_StyledString_Descriptor</b> object. 154 * @return Returns the result code. 155 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 156 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 157 * @since 14 158 */ 159 int32_t OH_ArkUI_UnmarshallStyledStringDescriptor( 160 uint8_t* buffer, size_t bufferSize, ArkUI_StyledString_Descriptor* descriptor); 161 162 /** 163 * @brief Serializes the styled string information into a byte array. 164 * 165 * @param buffer Byte array where the serialized data will be stored. 166 * @param bufferSize Length of the byte array. 167 * @param descriptor Pointer to an <b>ArkUI_StyledString_Descriptor</b> object. 168 * @param resultSize Actual length of the byte array. 169 * @return Returns the result code. 170 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 171 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 172 * Returns {@link ARKUI_ERROR_CODE_INVALID_STYLED_STRING} if the styled string is invalid. 173 * @since 14 174 */ 175 int32_t OH_ArkUI_MarshallStyledStringDescriptor( 176 uint8_t* buffer, size_t bufferSize, ArkUI_StyledString_Descriptor* descriptor, size_t* resultSize); 177 178 #ifdef __cplusplus 179 }; 180 #endif 181 182 #endif // ARKUI_NATIVE_STYLED_STRING_H 183 /** @} */ 184