1# @ohos.app.ability.dialogRequest (dialogRequest)
2
3The **dialogRequest** module provides APIs related to modal dialog box processing, including obtaining the request information (used to bind a modal dialog box) and request callback (used to set the request result).
4A modal dialog box is a system pop-up box that intercepts events (such as mouse, keyboard, and touchscreen events) triggered for the page displayed under it. The page can be operated only after the modal dialog box is destroyed.
5
6> **NOTE**
7>
8>  - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
9>  - The APIs provided by this module are used in ServiceExtensionAbilities. For a ServiceExtensionAbility that implements modal dialog boxes, you can use the APIs to obtain the request information and request callback and return the request result.
10
11## Modules to Import
12
13```ts
14import { dialogRequest } from '@kit.AbilityKit';
15```
16
17## dialogRequest.getRequestInfo
18
19getRequestInfo(want: Want): RequestInfo
20
21> **NOTE**
22>
23>  This API can be used by a ServiceExtensionAbility. If the ServiceExtensionAbility implements modal dialog boxes, the request information can be obtained from Want. If this API is used in other scenarios, no return value is obtained.
24
25Obtains the request information from Want.
26
27**System capability**: SystemCapability.Ability.AbilityRuntime.Core
28
29**Parameters**
30
31| Name| Type  | Mandatory| Description                       |
32| ---- | ------ | ---- | --------------------------- |
33| want  | [Want](js-apis-app-ability-want.md) | Yes  | Want passed in the request for a modal dialog box.|
34
35**Return value**
36
37| Type  | Description                    |
38| ------ | ------------------------ |
39| [RequestInfo](#requestinfo) | **RequestInfo** object obtained, which is used to bind a modal dialog box.|
40
41**Error codes**
42
43For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
44
45| ID| Error Message|
46| ------- | -------- |
47| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
48
49**Example**
50
51```ts
52import { AbilityConstant, UIAbility, Want, dialogRequest } from '@kit.AbilityKit';
53
54export default class EntryAbility extends UIAbility {
55  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
56    try {
57      let requestInfo = dialogRequest.getRequestInfo(want);
58    } catch (err) {
59      console.error(`getRequestInfo err= ${JSON.stringify(err)}`);
60    }
61  }
62}
63```
64
65## dialogRequest.getRequestCallback
66
67getRequestCallback(want: Want): RequestCallback
68
69Obtains the request callback from Want.
70
71> **NOTE**
72>
73>  This API can be used by a ServiceExtensionAbility. If the ServiceExtensionAbility implements modal dialog boxes, the request callback can be obtained from Want. If this API is used in other scenarios, no return value is obtained.
74
75**System capability**: SystemCapability.Ability.AbilityRuntime.Core
76
77**Parameters**
78
79| Name| Type  | Mandatory| Description                       |
80| ---- | ------ | ---- | --------------------------- |
81| want  | [Want](js-apis-app-ability-want.md) | Yes  | Want passed in the request for a modal dialog box.|
82
83**Return value**
84
85| Type  | Description                    |
86| ------ | ------------------------ |
87| [RequestCallback](#requestcallback) | **RequestCallback** object obtained, which is used to set the return result.|
88
89**Error codes**
90
91For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
92
93| ID| Error Message|
94| ------- | -------- |
95| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
96
97**Example**
98
99```ts
100import { AbilityConstant, UIAbility, Want, dialogRequest } from '@kit.AbilityKit';
101
102export default class EntryAbility extends UIAbility {
103  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
104    try {
105      let requestCallback = dialogRequest.getRequestCallback(want);
106    } catch(err) {
107      console.error(`getRequestInfo err= ${JSON.stringify(err)}`);
108    }
109  }
110}
111```
112
113## WindowRect<sup>10+</sup>
114
115Defines the location attributes of a modal dialog box.
116
117**Model restriction**: This API can be used only in the stage model.
118
119**System capability**: SystemCapability.Ability.AbilityRuntime.Core
120
121| Name| Type  | Mandatory| Description                       |
122| ---- | ------ | ---- | --------------------------- |
123| left  | number | Yes  | X-coordinate of the upper left corner of the dialog box.|
124| top  | number | Yes  | Y-coordinate of the upper left corner of the dialog box.|
125| width  | number | Yes  | Width of the dialog box.|
126| height  | number | Yes  | Height of the dialog box.|
127
128## RequestInfo
129
130Defines the request information, which is used as an input parameter for binding the modal dialog box.
131
132**Model restriction**: This API can be used only in the stage model.
133
134**System capability**: SystemCapability.Ability.AbilityRuntime.Core
135
136| Name     | Type      | Mandatory  | Description    |
137| ------------ | ------------------| ------ | ---------------------- |
138| windowRect<sup>10+</sup>            | [WindowRect](#windowrect10)    | No  | Location attributes of a modal dialog box.         |
139
140**Example**
141
142```ts
143import { AbilityConstant, UIAbility, Want, dialogRequest } from '@kit.AbilityKit';
144
145export default class EntryAbility extends UIAbility {
146  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
147    try {
148      let requestInfo = dialogRequest.getRequestInfo(want);
149      console.info(`getRequestInfo windowRect=, ${JSON.stringify(requestInfo.windowRect)}` );
150    } catch(err) {
151      console.error(`getRequestInfo err= ${JSON.stringify(err)}`);
152    }
153  }
154}
155```
156
157## ResultCode
158
159Enumerates the result codes of the request for the modal dialog box.
160
161**System capability**: SystemCapability.Ability.AbilityRuntime.Core
162
163| Name     | Value         | Description    |
164| ------------ | ------------------ | ---------------------- |
165| RESULT_OK            | 0          | The request succeeds.         |
166| RESULT_CANCEL        | 1          | The request fails.         |
167
168## RequestResult
169Defines the result of the request for the modal dialog box. It contains **ResultCode** and **ResultWant**.
170
171### Properties
172
173**Model restriction**: This API can be used only in the stage model.
174
175**System capability**: SystemCapability.Ability.AbilityRuntime.Core
176
177| Name| Type| Read-only| Optional| Description|
178| -------- | -------- | -------- | -------- | -------- |
179| result | [ResultCode](#resultcode) | No| No| Result code of the request.|
180| want<sup>10+</sup> | [Want](js-apis-app-ability-want.md)  | No| Yes| Want information, such as the ability name and bundle name.|
181
182## RequestCallback
183
184Provides a callback for setting the modal dialog box request result.
185
186**Model restriction**: This API can be used only in the stage model.
187
188### RequestCallback.setRequestResult
189
190setRequestResult(result: RequestResult): void
191
192Sets the result of the request for the modal dialog box.
193
194**Model restriction**: This API can be used only in the stage model.
195
196**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore
197
198**Parameters**
199
200| Name| Type| Mandatory| Description|
201| -------- | -------- | -------- | -------- |
202| result | [RequestResult](#requestresult) | Yes| Request result to set.|
203
204**Error codes**
205
206For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
207
208| ID| Error Message|
209| ------- | -------- |
210| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
211
212**Example**
213
214```ts
215import { AbilityConstant, UIAbility, Want, dialogRequest } from '@kit.AbilityKit';
216
217export default class EntryAbility extends UIAbility {
218  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
219    try {
220      let requestCallback = dialogRequest.getRequestCallback(want);
221      let myResult: dialogRequest.RequestResult = {
222        result : dialogRequest.ResultCode.RESULT_CANCEL,
223      };
224      requestCallback.setRequestResult(myResult);
225    } catch(err) {
226      console.error(`getRequestInfo err= ${JSON.stringify(err)}`);
227    }
228  }
229}
230```
231