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 * @file 18 * @kit ArkUI 19 */ 20 21 22 23import { Callback } from './@ohos.base'; 24import window from './@ohos.window'; 25/** 26 * uiExtension. 27 * 28 * @namespace uiExtension 29 * @syscap SystemCapability.ArkUI.ArkUI.Full 30 * @atomicservice 31 * @since 12 32 */ 33declare namespace uiExtension { 34 /** 35 * The proxy of the UIExtension window. 36 * 37 * @interface WindowProxy 38 * @syscap SystemCapability.ArkUI.ArkUI.Full 39 * @atomicservice 40 * @since 12 41 */ 42 interface WindowProxy { 43 /** 44 * Obtains the area where this window cannot be displayed, for example, the system bar area, notch, gesture area, and soft keyboard area. 45 * 46 * @param { window.AvoidAreaType } type - Type of the avoid area. 47 * @returns { window.AvoidArea } Area where the window cannot be displayed. 48 * @throws { BusinessError } 401 - Parameter error. Possible causes: 49 * <br> 1. Mandatory parameters are left unspecified. 50 * <br> 2. Incorrect parameters types. 51 * <br> 3. Parameter verification failed. 52 * @syscap SystemCapability.ArkUI.ArkUI.Full 53 * @atomicservice 54 * @since 12 55 */ 56 getWindowAvoidArea(type: window.AvoidAreaType): window.AvoidArea; 57 58 /** 59 * Subscribes to the event indicating changes to the area where the window cannot be displayed. 60 * 61 * @param { 'avoidAreaChange' } type - Event type. The value is fixed at 'avoidAreaChange', 62 * indicating the event of changes to the area where the window cannot be displayed. 63 * @param { Callback<AvoidAreaInfo> } callback - Callback used to return the avoid area information. 64 * @throws { BusinessError } 401 - Parameter error. Possible causes: 65 * <br> 1. Mandatory parameters are left unspecified. 66 * <br> 2. Incorrect parameters types. 67 * <br> 3. Parameter verification failed. 68 * @syscap SystemCapability.ArkUI.ArkUI.Full 69 * @atomicservice 70 * @since 12 71 */ 72 on(type: 'avoidAreaChange', callback: Callback<AvoidAreaInfo>): void; 73 74 /** 75 * Unsubscribes from the event indicating changes to the area where the window cannot be displayed. 76 * 77 * @param { 'avoidAreaChange' } type - Event type. The value is fixed at 'avoidAreaChange', 78 * indicating the event of changes to the area where the window cannot be displayed. 79 * @param { Callback<AvoidAreaInfo> } callback - Callback used to return the avoid area information. 80 * @throws { BusinessError } 401 - Parameter error. Possible causes: 81 * <br> 1. Mandatory parameters are left unspecified. 82 * <br> 2. Incorrect parameters types. 83 * <br> 3. Parameter verification failed. 84 * @syscap SystemCapability.ArkUI.ArkUI.Full 85 * @atomicservice 86 * @since 12 87 */ 88 off(type: 'avoidAreaChange', callback?: Callback<AvoidAreaInfo>): void; 89 90 /** 91 * Subscribes to the window size change event of the host application. 92 * 93 * @param { 'windowSizeChange' } type - Event type. The value is fixed at 'windowSizeChange', indicating the window size change event. 94 * @param { Callback<window.Size> } callback - Callback used to return the window size. 95 * @throws { BusinessError } 401 - Parameter error. Possible causes: 96 * <br> 1. Mandatory parameters are left unspecified. 97 * <br> 2. Incorrect parameters types. 98 * <br> 3. Parameter verification failed. 99 * @syscap SystemCapability.ArkUI.ArkUI.Full 100 * @atomicservice 101 * @since 12 102 */ 103 on(type: 'windowSizeChange', callback: Callback<window.Size>): void; 104 105 /** 106 * Unsubscribes from the window size change event of the host application. 107 * 108 * @param { 'windowSizeChange' } type - Event type. The value is fixed at 'windowSizeChange', indicating the window size change event. 109 * @param { Callback<window.Size> } callback - Callback used to return the window size. 110 * @throws { BusinessError } 401 - Parameter error. Possible causes: 111 * <br> 1. Mandatory parameters are left unspecified. 112 * <br> 2. Incorrect parameters types. 113 * <br> 3. Parameter verification failed. 114 * @syscap SystemCapability.ArkUI.ArkUI.Full 115 * @atomicservice 116 * @since 12 117 */ 118 off(type: 'windowSizeChange', callback?: Callback<window.Size>): void; 119 120 /** 121 * Subscribes to changes in the position and size of the component (EmbeddedComponent or UIExtensionComponent). This API can be used only on 2-in-1 devices. 122 * 123 * @param { 'rectChange' } type - Event type. The value is fixed at 'rectChange', 124 * indicating the rectangle change event for the component (EmbeddedComponent or UIExtensionComponent). 125 * @param { 'number' } reasons - The reasons of component rect change. 126 * @param { Callback<RectChangeOptions> } callback - Callback used to return the RectChangeOptions. 127 * @throws { BusinessError } 401 - Parameter error. Possible cause: 128 * <br> 1. Mandatory parameters are left unspecified. 129 * <br> 2. Incorrect parameters types. 130 * <br> 3. Parameter verification failed. 131 * @throws { BusinessError } 801 - Capability not supported. Failed to call the API due to limited device capabilities. 132 * @syscap SystemCapability.ArkUI.ArkUI.Full 133 * @atomicservice 134 * @since 14 135 */ 136 on(type: 'rectChange', reasons: number, callback: Callback<RectChangeOptions>): void; 137 138 /** 139 * Unsubscribes from changes in the position and size of the component (EmbeddedComponent or UIExtensionComponent). 140 * This API can be used only on 2-in-1 devices. 141 * 142 * @param { 'rectChange' } type - Event type. The value is fixed at 'rectChange', 143 * indicating the rectangle change event for the component (EmbeddedComponent or UIExtensionComponent). 144 * @param { Callback<RectChangeOptions> } callback - Callback used to return the RectChangeOptions. 145 * @throws { BusinessError } 401 - Parameter error. Possible cause: 146 * <br> 1. Mandatory parameters are left unspecified. 147 * <br> 2. Incorrect parameters types. 148 * <br> 3. Parameter verification failed. 149 * @throws { BusinessError } 801 - Capability not supported. Failed to call the API due to limited device capabilities. 150 * @syscap SystemCapability.ArkUI.ArkUI.Full 151 * @atomicservice 152 * @since 14 153 */ 154 off(type: 'rectChange', callback?: Callback<RectChangeOptions>): void; 155 156 /** 157 * Sets whether to hide insecure windows. 158 * When called by modal UIExtension and shouldHide == false, the "ohos.permission.ALLOW_SHOW_NON_SECURE_WINDOWS" permission is required. 159 * 160 * @permission ohos.permission.ALLOW_SHOW_NON_SECURE_WINDOWS 161 * @param { boolean } shouldHide - Whether to hide insecure windows. The value true means to hide insecure windows, and false means the opposite. 162 * @returns { Promise<void> } - The promise returned by the function. 163 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 164 * @throws { BusinessError } 401 - Parameter error. Possible causes: 165 * <br> 1. Mandatory parameters are left unspecified. 166 * <br> 2. Incorrect parameters types. 167 * <br> 3. Parameter verification failed. 168 * @throws { BusinessError } 1300002 - Abnormal state. Possible causes: 169 * <br> 1. Permission denied. Interface caller does not have permission "ohos.permission.ALLOW_SHOW_NON_SECURE_WINDOWS". 170 * <br> 2. The UIExtension window proxy is abnormal. 171 * @throws { BusinessError } 1300003 - This window manager service works abnormally. 172 * @syscap SystemCapability.ArkUI.ArkUI.Full 173 * @systemapi 174 * @since 12 175 */ 176 hideNonSecureWindows(shouldHide: boolean): Promise<void>; 177 178 /** 179 * Creates a subwindow for this window proxy. This API uses a promise to return the result. 180 * 181 * @param { string } name - Name of the subwindow. 182 * @param { window.SubWindowOptions } subWindowOptions - Parameters used for creating the subwindow. 183 * @returns { Promise<window.Window> } Promise used to return the subwindow. 184 * @throws { BusinessError } 401 - Parameter error. Possible causes: 185 * <br> 1. Mandatory parameters are left unspecified. 186 * <br> 2. Incorrect parameters types. 187 * <br> 3. Parameter verification failed. 188 * @throws { BusinessError } 801 - Capability not supported. Failed to call the API due to limited device capabilities. 189 * @throws { BusinessError } 1300002 - This window state is abnormal. 190 * @syscap SystemCapability.ArkUI.ArkUI.Full 191 * @StageModelOnly 192 * @atomicservice 193 * @since 12 194 */ 195 createSubWindowWithOptions(name: string, subWindowOptions: window.SubWindowOptions): Promise<window.Window>; 196 197 /** 198 * Adds or deletes the watermark flag for this window. This API uses a promise to return the result. 199 * 200 * @param { boolean } enable - Whether to add or delete the flag. The value true means to add the watermark flag, 201 * and false means to delete the watermark flag. 202 * @returns { Promise<void> } - The promise returned by the function 203 * @throws { BusinessError } 1300002 - The UIExtension window proxy is abnormal. 204 * @throws { BusinessError } 1300003 - This window manager service works abnormally. 205 * @throws { BusinessError } 1300008 - The display device is abnormal. 206 * @syscap SystemCapability.ArkUI.ArkUI.Full 207 * @systemapi 208 * @since 12 209 */ 210 setWaterMarkFlag(enable: boolean): Promise<void>; 211 212 /** 213 * Sets the events that the component (EmbeddedComponent or UIExtensionComponent) will occupy, 214 * preventing the host from responding to these events within the component's area. 215 * 216 * @param { EventFlag } eventFlags - Type of events to occupy. For details about the available values, see {@link uiExtension.EventFlag }. 217 * @returns { Promise<void> } - The promise returned by the function 218 * @throws { BusinessError } 401 - Parameter error. Possible cause: 219 * <br> 1. Mandatory parameters are left unspecified. 220 * <br> 2. Incorrect parameters types. 221 * <br> 3. Parameter verification failed. 222 * @throws { BusinessError } 1300002 - This window state is abnormal. 223 * @throws { BusinessError } 1300003 - This window manager service works abnormally. 224 * @syscap SystemCapability.ArkUI.ArkUI.Full 225 * @atomicservice 226 * @since 18 227 */ 228 occupyEvents(eventFlags: number): Promise<void>; 229 230 /** 231 * The properties of the UIExtension window 232 * 233 * @type { WindowProxyProperties } 234 * @syscap SystemCapability.ArkUI.ArkUI.Full 235 * @atomicservice 236 * @since 14 237 */ 238 properties: WindowProxyProperties; 239 } 240 241 /** 242 * Gesture event type 243 * 244 * @enum { number } 245 * @syscap SystemCapability.ArkUI.ArkUI.Full 246 * @atomicservice 247 * @since 18 248 */ 249 enum EventFlag { 250 /** 251 * None gesture event 252 * 253 * @syscap SystemCapability.ArkUI.ArkUI.Full 254 * @atomicservice 255 * @since 18 256 */ 257 EVENT_NONE = 0x00000000, 258 /** 259 * Pan gesture left events 260 * 261 * @syscap SystemCapability.ArkUI.ArkUI.Full 262 * @atomicservice 263 * @since 18 264 */ 265 EVENT_PAN_GESTURE_LEFT = 0x00000001, 266 /** 267 * Pan gesture right events 268 * 269 * @syscap SystemCapability.ArkUI.ArkUI.Full 270 * @atomicservice 271 * @since 18 272 */ 273 EVENT_PAN_GESTURE_RIGHT = 0x00000002, 274 /** 275 * Pan gesture up events 276 * 277 * @syscap SystemCapability.ArkUI.ArkUI.Full 278 * @atomicservice 279 * @since 18 280 */ 281 EVENT_PAN_GESTURE_UP = 0x00000004, 282 /** 283 * Pan gesture down events 284 * 285 * @syscap SystemCapability.ArkUI.ArkUI.Full 286 * @atomicservice 287 * @since 18 288 */ 289 EVENT_PAN_GESTURE_DOWN = 0x00000008, 290 /** 291 * Click gesture events 292 * 293 * @syscap SystemCapability.ArkUI.ArkUI.Full 294 * @atomicservice 295 * @since 18 296 */ 297 EVENT_CLICK = 0x00000100, 298 /** 299 * Long press gesture events 300 * 301 * @syscap SystemCapability.ArkUI.ArkUI.Full 302 * @atomicservice 303 * @since 18 304 */ 305 EVENT_LONG_PRESS = 0x00000200, 306 } 307 308 /** 309 * Defines the avoid area information. 310 * 311 * @interface AvoidAreaInfo 312 * @syscap SystemCapability.ArkUI.ArkUI.Full 313 * @atomicservice 314 * @since 12 315 */ 316 interface AvoidAreaInfo { 317 /** 318 * Type of the area where the window cannot be displayed. 319 * 320 * @type { window.AvoidAreaType } 321 * @syscap SystemCapability.ArkUI.ArkUI.Full 322 * @atomicservice 323 * @since 12 324 */ 325 type: window.AvoidAreaType; 326 327 /** 328 * Area where the window cannot be displayed. 329 * 330 * @type { window.AvoidArea } 331 * @syscap SystemCapability.ArkUI.ArkUI.Full 332 * @atomicservice 333 * @since 12 334 */ 335 area: window.AvoidArea; 336 } 337 338 /** 339 * Properties of UIExtension window 340 * 341 * @interface WindowProxyProperties 342 * @syscap SystemCapability.ArkUI.ArkUI.Full 343 * @atomicservice 344 * @since 14 345 * 346 */ 347 interface WindowProxyProperties { 348 /** 349 * Position and size of the component (EmbeddedComponent or UIExtensionComponent). 350 * 351 * @type { window.Rect } 352 * @syscap SystemCapability.ArkUI.ArkUI.Full 353 * @atomicservice 354 * @since 14 355 */ 356 uiExtensionHostWindowProxyRect: window.Rect; 357 } 358 359 /** 360 * Defines the reason of component rect change 361 * 362 * @enum { number } 363 * @syscap SystemCapability.ArkUI.ArkUI.Full 364 * @atomicservice 365 * @since 14 366 */ 367 enum RectChangeReason { 368 /** 369 * The rectangle of the host window containing the component changes. 370 * 371 * @syscap SystemCapability.ArkUI.ArkUI.Full 372 * @atomicservice 373 * @since 14 374 */ 375 HOST_WINDOW_RECT_CHANGE = 0x0001, 376 } 377 378 /** 379 * Rect change options 380 * 381 * @interface RectChangeOptions 382 * @syscap SystemCapability.ArkUI.ArkUI.Full 383 * @atomicservice 384 * @since 14 385 */ 386 interface RectChangeOptions { 387 /** 388 * New values of the rectangle of the component after the change. 389 * 390 * @type { window.Rect } 391 * @syscap SystemCapability.ArkUI.ArkUI.Full 392 * @atomicservice 393 * @since 14 394 */ 395 rect: window.Rect, 396 397 /** 398 * Reason for the rectangle change. 399 * 400 * @type { RectChangeReason } 401 * @syscap SystemCapability.ArkUI.ArkUI.Full 402 * @atomicservice 403 * @since 14 404 */ 405 reason: RectChangeReason 406 } 407} 408 409export default uiExtension; 410