• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Building a Dialog Box
2
3
4You can display a custom dialog box by creating a dialog controller or by creating a custom dialog content object, and then setting its styles and content.
5
6
7[Displaying a custom dialog box through a dialog controller](#displaying-a-custom-dialog-box-through-a-dialog-controller): In this approach, you use the APIs defined in a struct named **ArkUI_NativeDialogAPI_x** (where *x* denotes the version) for dialog box control.
8
9
10[Displaying a custom dialog box through a custom dialog content object](#displaying-a-custom-dialog-box-through-a-custom-dialog-content-object): In this approach, you use the APIs defined in the functions of [native_dialog.h](../reference/apis-arkui/native__dialog_8h.md#functions).
11
12
13> **NOTE**
14>
15> - For details about how to display a custom dialog box through a dialog controller, see [openCustomDialogWithController](../reference/apis-arkui/js-apis-arkui-UIContext.md#opencustomdialogwithcontroller18).
16>
17> - For details about how to display a custom dialog box through a custom dialog content object, see [openCustomDialog](../reference/apis-arkui/js-apis-arkui-UIContext.md#opencustomdialog12).
18>
19> - [OH_ArkUI_QueryModuleInterfaceByName](../reference/apis-arkui/_ark_u_i___native_module.md#oh_arkui_querymoduleinterfacebyname) is used to obtain a collection of native module APIs of a specified type. You can call APIs in the native module using the returned data of the **ArkUI_NativeDialogHandle** type.
20
21## Creating and Destroying a Custom Dialog Box
22
23### Displaying a Custom Dialog Box Through a Dialog Controller
24
25- Creating a Dialog Controller
26  [ArkUI_NativeDialogHandle](../reference/apis-arkui/_ark_u_i___native_module.md#arkui_nativedialoghandle) represents a pointer to the dialog controller, which you can create by calling the [create](../reference/apis-arkui/_ark_u_i___native_dialog_a_p_i__1.md#create) API of [ArkUI_NativeDialogAPI_x](../reference/apis-arkui/_ark_u_i___native_dialog_a_p_i__1.md).
27This API returns data of the **ArkUI_NativeDialogHandle** type.
28  ```
29  ArkUI_NativeDialogAPI_1 *dialogAPI = reinterpret_cast<ArkUI_NativeDialogAPI_1 *>(
30      OH_ArkUI_QueryModuleInterfaceByName(ARKUI_NATIVE_DIALOG, "ArkUI_NativeDialogAPI_1"));
31  auto dialogController = dialogAPI->create();
32  ```
33
34- Destroying the Dialog Controller<br>When dialog box operations are no longer needed, actively call the **dispose** API to destroy the dialog controller object.
35  ```
36  ArkUI_NativeDialogAPI_1 *dialogAPI = reinterpret_cast<ArkUI_NativeDialogAPI_1 *>(
37      OH_ArkUI_QueryModuleInterfaceByName(ARKUI_NATIVE_DIALOG, "ArkUI_NativeDialogAPI_1"));
38  dialogAPI->dispose(dialogController);
39  ```
40
41### Displaying a Custom Dialog Box Through a Custom Dialog Content Object
42
43- Creating a Dialog Content Object
44  You can create a custom dialog content object [ArkUI_CustomDialogOptions](../reference/apis-arkui/_ark_u_i___native_module.md#arkui_customdialogoptions) by calling the [OH_ArkUI_CustomDialog_CreateOptions](../reference/apis-arkui/_ark_u_i___native_module.md#oh_arkui_customdialog_createoptions) API,
45which returns a pointer of the **ArkUI_CustomDialogOptions** type.
46  ```
47  auto textNode = std::make_shared<ArkUITextNode>();
48  auto dialogOptions = OH_ArkUI_CustomDialog_CreateOptions(textNode->GetHandle());
49  ```
50  > **NOTE**
51  >
52  > For details about how to declare **ArkUITextNode**, refer to the implementation of the text component in the [ArkUINode.h](../ui/ndk-access-the-arkts-page.md) file.
53
54- Destroying a Dialog Content Object<br>When dialog box operations are no longer needed, actively call the [OH_ArkUI_CustomDialog_DisposeOptions](../reference/apis-arkui/_ark_u_i___native_module.md#oh_arkui_customdialog_disposeoptions) API to destroy the dialog content object.
55  ```
56  OH_ArkUI_CustomDialog_DisposeOptions(dialogOptions);
57  ```
58
59## Setting Dialog Box Styles
60
61You can set the alignment, offset, corner radius of the background, background color, mask color, and region of the dialog box.
62
631. Create a dialog box content node.
64   ```
65   ArkUI_NodeHandle CreateDialogContent() {
66       ArkUI_NativeNodeAPI_1 *nodeAPI = reinterpret_cast<ArkUI_NativeNodeAPI_1 *>(
67           OH_ArkUI_QueryModuleInterfaceByName(ARKUI_NATIVE_NODE, "ArkUI_NativeNodeAPI_1"));
68       ArkUI_NodeHandle text = nodeAPI->createNode(ARKUI_NODE_TEXT);
69       ArkUI_NumberValue textWidthValue[] = {{.f32 = 300}};
70       ArkUI_AttributeItem textWidthItem = {.value = textWidthValue,
71                                            .size = sizeof(textWidthValue) / sizeof(ArkUI_NumberValue)};
72       nodeAPI->setAttribute(text, NODE_WIDTH, &textWidthItem);
73       ArkUI_NumberValue textHeightValue[] = {{.f32 = 300}};
74       ArkUI_AttributeItem textHeightItem = {.value = textHeightValue,
75                                             .size = sizeof(textWidthValue) / sizeof(ArkUI_NumberValue)};
76       nodeAPI->setAttribute(text, NODE_HEIGHT, &textHeightItem);
77       ArkUI_NodeHandle span = nodeAPI->createNode(ARKUI_NODE_SPAN);
78       ArkUI_AttributeItem spanItem = {.string = "This is a dialog box"};
79       nodeAPI->setAttribute(span, NODE_SPAN_CONTENT, &spanItem);
80       ArkUI_NodeHandle imageSpan = nodeAPI->createNode(ARKUI_NODE_IMAGE_SPAN);
81       ArkUI_AttributeItem imageSpanItem = {.string = "/pages/common/sky.jpg"};
82       nodeAPI->setAttribute(imageSpan, NODE_IMAGE_SPAN_SRC, &imageSpanItem);
83       ArkUI_NumberValue imageSpanWidthValue[] = {{.f32 = 300}};
84       ArkUI_AttributeItem imageSpanWidthItem = {.value = imageSpanWidthValue,
85                                                 .size = sizeof(textWidthValue) / sizeof(ArkUI_NumberValue)};
86       nodeAPI->setAttribute(imageSpan, NODE_WIDTH, &imageSpanWidthItem);
87       ArkUI_NumberValue imageSpanHeightValue[] = {{.f32 = 200}};
88       ArkUI_AttributeItem imageSpanHeightItem = {.value = imageSpanHeightValue,
89                                                  .size = sizeof(textWidthValue) / sizeof(ArkUI_NumberValue)};
90       nodeAPI->setAttribute(imageSpan, NODE_HEIGHT, &imageSpanHeightItem);
91       nodeAPI->addChild(text, span);
92       nodeAPI->addChild(text, imageSpan);
93       return text;
94   }
95   ```
96
972. Control dialog box styles using either of the following methods. For details about the dialog box APIs, see [native_dialog.h](../reference/apis-arkui/native__dialog_8h.md).
98
99- Using the controller
100   ```
101   void ShowDialog() {
102       ArkUI_NativeDialogAPI_1 *dialogAPI = reinterpret_cast<ArkUI_NativeDialogAPI_1 *>(
103           OH_ArkUI_QueryModuleInterfaceByName(ARKUI_NATIVE_DIALOG, "ArkUI_NativeDialogAPI_1"));
104       if (!dialogController) {
105           dialogController = dialogAPI->create();
106       }
107       auto contentNode = CreateDialogContent();
108       dialogAPI->setContent(dialogController, contentNode);
109       dialogAPI->setContentAlignment(dialogController, static_cast<int32_t>(ARKUI_ALIGNMENT_BOTTOM), 0, 0);
110       dialogAPI->setBackgroundColor(dialogController, 0xffffffff);
111       dialogAPI->setCornerRadius(dialogController, 6, 6, 6, 6);
112       dialogAPI->setModalMode(dialogController, false);
113       dialogAPI->setAutoCancel(dialogController, true);
114       dialogAPI->show(dialogController, false);
115   }
116   ```
117
118- Using **dialogOptions**
119   ```
120   constexpr int32_t id = 0;
121   void openDialogCallBack(int32_t dialogId) {
122       id = dialogId;
123   }
124   void OpenCustomDialog() {
125       auto contentNode = CreateDialogContent();
126       auto dialogOptions = OH_ArkUI_CustomDialog_CreateOptions(contentNode);
127       OH_ArkUI_CustomDialog_SetAlignment(dialogOptions, static_cast<int32_t>(ARKUI_ALIGNMENT_BOTTOM), 0, 0);
128       OH_ArkUI_CustomDialog_SetBackgroundColor(dialogOptions, 0xffffffff);
129       OH_ArkUI_CustomDialog_SetCornerRadius(dialogOptions, 6, 6, 6, 6);
130       OH_ArkUI_CustomDialog_SetModalMode(dialogOptions, false);
131       OH_ArkUI_CustomDialog_SetAutoCancel(dialogOptions, true);
132       OH_ArkUI_CustomDialog_SetBorderWidth(dialogOptions, 2, 2, 2, 2, ARKUI_LENGTH_METRIC_UNIT_PX);
133       OH_ArkUI_CustomDialog_SetBorderStyle(dialogOptions, ARKUI_BORDER_STYLE_SOLID, ARKUI_BORDER_STYLE_SOLID,ARKUI_BORDER_STYLE_SOLID, ARKUI_BORDER_STYLE_SOLID);
134       OH_ArkUI_CustomDialog_OpenDialog(dialogOptions, openDialogCallBack);
135   }
136   ```
137
1383. Close the dialog box using either of the following methods:
139
140- Using the controller
141   ```
142   void CloseDialog() {
143       ArkUI_NativeDialogAPI_1 *dialogAPI = reinterpret_cast<ArkUI_NativeDialogAPI_1 *>(
144           OH_ArkUI_QueryModuleInterfaceByName(ARKUI_NATIVE_DIALOG, "ArkUI_NativeDialogAPI_1"));
145       dialogAPI->close(dialogController);
146   }
147   ```
148
149- Using **dialogOptions**
150   ```
151   void CloseCustomDialog() {
152       OH_ArkUI_CustomDialog_CloseDialog(id);
153   }
154   ```
155
156## Interacting with the Dialog Box
157
158You can create an interactive page to open or close a dialog box.
159
1601. Create a button that, when clicked, will trigger the display of a dialog box. For details about how to obtain and use nodes of the ArkUI_NodeContentHandle type, see [Integrating with ArkTS Pages](ndk-access-the-arkts-page.md).
161   ```
162   constexpr int32_t BUTTON_CLICK_ID = 1;
163   bool isShown = false;
164   ArkUI_NativeDialogHandle dialogController;
165   ArkUI_NodeHandle buttonNode;
166
167   void MainViewMethod(ArkUI_NodeContentHandle handle) {
168       ArkUI_NativeNodeAPI_1 *nodeAPI = reinterpret_cast<ArkUI_NativeNodeAPI_1 *>(
169           OH_ArkUI_QueryModuleInterfaceByName(ARKUI_NATIVE_NODE, "ArkUI_NativeNodeAPI_1"));
170       ArkUI_NodeHandle column = nodeAPI->createNode(ARKUI_NODE_COLUMN);
171       ArkUI_NumberValue widthValue[] = {{.f32 = 300}};
172       ArkUI_AttributeItem widthItem = {.value = widthValue, .size = sizeof(widthValue) / sizeof(ArkUI_NumberValue)};
173       nodeAPI->setAttribute(column, NODE_WIDTH, &widthItem);
174       ArkUI_NumberValue heightValue[] = {{.f32 = 300}};
175       ArkUI_AttributeItem heightItem = {.value = heightValue, .size = sizeof(heightValue) / sizeof(ArkUI_NumberValue)};
176       nodeAPI->setAttribute(column, NODE_HEIGHT, &heightItem);
177
178       buttonNode = nodeAPI->createNode(ARKUI_NODE_BUTTON);
179       ArkUI_NumberValue buttonWidthValue[] = {{.f32 = 200}};
180       ArkUI_AttributeItem buttonWidthItem = {.value = buttonWidthValue,
181                                              .size = sizeof(buttonWidthValue) / sizeof(ArkUI_NumberValue)};
182       nodeAPI->setAttribute(buttonNode, NODE_WIDTH, &buttonWidthItem);
183       ArkUI_NumberValue buttonHeightValue[] = {{.f32 = 50}};
184       ArkUI_AttributeItem buttonHeightItem = {.value = buttonHeightValue,
185                                               .size = sizeof(buttonHeightValue) / sizeof(ArkUI_NumberValue)};
186       nodeAPI->setAttribute(buttonNode, NODE_HEIGHT, &buttonHeightItem);
187       ArkUI_AttributeItem labelItem = {.string = "Click Dialog Box"};
188       nodeAPI->setAttribute(buttonNode, NODE_BUTTON_LABEL, &labelItem);
189       ArkUI_NumberValue buttonTypeValue[] = {{.i32 = static_cast<int32_t>(ARKUI_BUTTON_TYPE_NORMAL)}};
190       ArkUI_AttributeItem buttonTypeItem = {.value = buttonTypeValue,
191                                             .size = sizeof(buttonTypeValue) / sizeof(ArkUI_NumberValue)};
192       nodeAPI->setAttribute(buttonNode, NODE_BUTTON_TYPE, &buttonTypeItem);
193       nodeAPI->registerNodeEvent(buttonNode, NODE_ON_CLICK, BUTTON_CLICK_ID, nullptr);
194       nodeAPI->addNodeEventReceiver(buttonNode, OnButtonClicked);
195       nodeAPI->addChild(column, buttonNode);
196       OH_ArkUI_NodeContent_AddNode(handle, column);
197   }
198   ```
199
2002. Create a button event callback function to trigger the display or closure of the dialog box when the button is clicked.
201
202- Using the controller
203   ```
204   void OnButtonClicked(ArkUI_NodeEvent *event) {
205       if (!event || !buttonNode) {
206           return;
207       }
208       auto eventId = OH_ArkUI_NodeEvent_GetTargetId(event);
209       if (eventId == BUTTON_CLICK_ID) {
210           ArkUI_NativeNodeAPI_1 *nodeAPI = reinterpret_cast<ArkUI_NativeNodeAPI_1 *>(
211               OH_ArkUI_QueryModuleInterfaceByName(ARKUI_NATIVE_NODE, "ArkUI_NativeNodeAPI_1"));
212           if (isShown) {
213               isShown = false;
214               ArkUI_AttributeItem labelItem = {.string = "Show Dialog Box"};
215               nodeAPI->setAttribute(buttonNode, NODE_BUTTON_LABEL, &labelItem);
216               CloseDialog();
217           } else {
218               isShown = true;
219               ArkUI_AttributeItem labelItem = {.string = "Close Dialog Box"};
220               nodeAPI->setAttribute(buttonNode, NODE_BUTTON_LABEL, &labelItem);
221               ShowDialog();
222           }
223       }
224   }
225   ```
226
227- Using **dialogOptions**
228   ```
229   constexpr int32_t id = 0;
230   void openDialogCallBack(int32_t dialogId) {
231       id = dialogId;
232   }
233   void OnButtonClicked(ArkUI_NodeEvent *event) {
234       if (!event || !buttonNode) {
235           return;
236       }
237       auto eventId = OH_ArkUI_NodeEvent_GetTargetId(event);
238       if (eventId == BUTTON_CLICK_ID) {
239           ArkUI_NativeNodeAPI_1 *nodeAPI = reinterpret_cast<ArkUI_NativeNodeAPI_1 *>(
240               OH_ArkUI_QueryModuleInterfaceByName(ARKUI_NATIVE_NODE, "ArkUI_NativeNodeAPI_1"));
241           if (isShown) {
242               isShown = false;
243               ArkUI_AttributeItem labelItem = {.string = "Show Dialog Box"};
244               nodeAPI->setAttribute(buttonNode, NODE_BUTTON_LABEL, &labelItem);
245               CloseCustomDialog();
246           } else {
247               isShown = true;
248               ArkUI_AttributeItem labelItem = {.string = "Close Dialog Box"};
249               nodeAPI->setAttribute(buttonNode, NODE_BUTTON_LABEL, &labelItem);
250               OpenCustomDialog();
251           }
252       }
253   }
254   ```
255
256   ![en-us_image_0000001902966196](figures/en-us_image_0000001902966196.gif)
257
258
259## Managing the Dialog Box Lifecycle
260
261Dialog boxes have four lifecycle events: **registerOnWillAppear**, **registerOnDidAppear**, **registerOnWillDisappear**, and **registerOnDidDisappear**.
262These lifecycle APIs must be called before the **show** API is invoked. The sequence of lifecycle events is as follows:
263registerOnWillAppear -> The dialog box display animation starts -> The dialog box display animation ends -> registerOnDidAppear -> The dialog box is fully displayed ->
264registerOnWillDisappear -> The dialog box exit animation starts -> The dialog box exit animation ends -> registerOnDidDisappear -> The dialog box is fully closed
265
266The following is an example of creating a dialog box that triggers lifecycle callback functions when the dialog box is displayed and closed. For details about how to obtain and use nodes of the ArkUI_NodeContentHandle type, see [Integrating with ArkTS Pages](ndk-access-the-arkts-page.md).
267   ```
268    ArkUI_NodeHandle CreateDialogContent() {
269        ArkUI_NativeNodeAPI_1 *nodeAPI = reinterpret_cast<ArkUI_NativeNodeAPI_1 *>(
270            OH_ArkUI_QueryModuleInterfaceByName(ARKUI_NATIVE_NODE, "ArkUI_NativeNodeAPI_1"));
271        ArkUI_NodeHandle text = nodeAPI->createNode(ARKUI_NODE_TEXT);
272        ArkUI_NumberValue textWidthValue[] = {{.f32 = 300}};
273        ArkUI_AttributeItem textWidthItem = {.value = textWidthValue,
274                                             .size = sizeof(textWidthValue) / sizeof(ArkUI_NumberValue)};
275        nodeAPI->setAttribute(text, NODE_WIDTH, &textWidthItem);
276        ArkUI_NumberValue textHeightValue[] = {{.f32 = 300}};
277        ArkUI_AttributeItem textHeightItem = {.value = textHeightValue,
278                                              .size = sizeof(textWidthValue) / sizeof(ArkUI_NumberValue)};
279        nodeAPI->setAttribute(text, NODE_HEIGHT, &textHeightItem);
280        ArkUI_NodeHandle span = nodeAPI->createNode(ARKUI_NODE_SPAN);
281        ArkUI_AttributeItem spanItem = {.string = "This is a dialog box"};
282        nodeAPI->setAttribute(span, NODE_SPAN_CONTENT, &spanItem);
283        ArkUI_NodeHandle imageSpan = nodeAPI->createNode(ARKUI_NODE_IMAGE_SPAN);
284        ArkUI_AttributeItem imageSpanItem = {.string = "/pages/common/sky.jpg"};
285        nodeAPI->setAttribute(imageSpan, NODE_IMAGE_SPAN_SRC, &imageSpanItem);
286        ArkUI_NumberValue imageSpanWidthValue[] = {{.f32 = 300}};
287        ArkUI_AttributeItem imageSpanWidthItem = {.value = imageSpanWidthValue,
288                                                  .size = sizeof(textWidthValue) / sizeof(ArkUI_NumberValue)};
289        nodeAPI->setAttribute(imageSpan, NODE_WIDTH, &imageSpanWidthItem);
290        ArkUI_NumberValue imageSpanHeightValue[] = {{.f32 = 200}};
291        ArkUI_AttributeItem imageSpanHeightItem = {.value = imageSpanHeightValue,
292                                                   .size = sizeof(textWidthValue) / sizeof(ArkUI_NumberValue)};
293        nodeAPI->setAttribute(imageSpan, NODE_HEIGHT, &imageSpanHeightItem);
294        nodeAPI->addChild(text, span);
295        nodeAPI->addChild(text, imageSpan);
296        return text;
297    }
298    void OnWillAppearCallBack(void* userdata) {
299        OH_LOG_Print(LOG_APP, LOG_INFO, LOG_PRINT_DOMAIN, "CustomDialogContentTest", "OnWillAppearCallBack");
300    }
301    void OnDidAppearCallBack(void* userdata) {
302        OH_LOG_Print(LOG_APP, LOG_INFO, LOG_PRINT_DOMAIN, "CustomDialogContentTest", "OnDidAppearCallBack");
303    }
304    void OnWillDisappearCallBack(void* userdata) {
305        OH_LOG_Print(LOG_APP, LOG_INFO, LOG_PRINT_DOMAIN, "CustomDialogContentTest", "OnWillDisappearCallBack");
306    }
307    void OnDidDisappearCallBack(void* userdata) {
308        OH_LOG_Print(LOG_APP, LOG_INFO, LOG_PRINT_DOMAIN, "CustomDialogContentTest", "OnDidDisappearCallBack");
309    }
310    void ShowDialog() {
311        ArkUI_NativeDialogAPI_3 *dialogAPI = reinterpret_cast<ArkUI_NativeDialogAPI_3 *>(
312            OH_ArkUI_QueryModuleInterfaceByName(ARKUI_NATIVE_DIALOG, "ArkUI_NativeDialogAPI_3"));
313        auto customDialog = dialogAPI->nativeDialogAPI1.create();
314        auto contentNode = CreateDialogContent();
315        dialogAPI->nativeDialogAPI1.setContent(customDialog, contentNode);
316        dialogAPI->nativeDialogAPI1.setAutoCancel(customDialog, true);
317        dialogAPI->registerOnWillAppear(customDialog, nullptr, OnWillAppearCallBack);
318        dialogAPI->registerOnDidAppear(customDialog, nullptr, OnDidAppearCallBack);
319        dialogAPI->registerOnWillDisappear(customDialog, nullptr, OnWillDisappearCallBack);
320        dialogAPI->registerOnDidDisappear(customDialog, nullptr, OnDidDisappearCallBack);
321        dialogAPI->nativeDialogAPI1.show(customDialog, false);
322    }
323   ```
324