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 * Get the avoid 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 * Register the callback of avoidAreaChange. 60 * 61 * @param { 'avoidAreaChange' } type - The value is fixed at 'avoidAreaChange', indicating the event of changes to the avoid area. 62 * @param { Callback<AvoidAreaInfo> } callback - Callback used to return the avoid area information. 63 * @throws { BusinessError } 401 - Parameter error. Possible causes: 64 * <br> 1. Mandatory parameters are left unspecified. 65 * <br> 2. Incorrect parameters types. 66 * <br> 3. Parameter verification failed. 67 * @syscap SystemCapability.ArkUI.ArkUI.Full 68 * @atomicservice 69 * @since 12 70 */ 71 on(type: 'avoidAreaChange', callback: Callback<AvoidAreaInfo>): void; 72 73 /** 74 * Unregister the callback of avoidAreaChange. 75 * 76 * @param { 'avoidAreaChange' } type - The value is fixed at 'avoidAreaChange', indicating the event of changes to the avoid area. 77 * @param { Callback<AvoidAreaInfo> } callback - Callback used to return the avoid area information. 78 * @throws { BusinessError } 401 - Parameter error. Possible causes: 79 * <br> 1. Mandatory parameters are left unspecified. 80 * <br> 2. Incorrect parameters types. 81 * <br> 3. Parameter verification failed. 82 * @syscap SystemCapability.ArkUI.ArkUI.Full 83 * @atomicservice 84 * @since 12 85 */ 86 off(type: 'avoidAreaChange', callback?: Callback<AvoidAreaInfo>): void; 87 88 /** 89 * Register the callback of windowSizeChange. 90 * 91 * @param { 'windowSizeChange' } type - The value is fixed at 'windowSizeChange', indicating the window size change event. 92 * @param { Callback<window.Size> } callback - Callback used to return the window size. 93 * @throws { BusinessError } 401 - Parameter error. Possible causes: 94 * <br> 1. Mandatory parameters are left unspecified. 95 * <br> 2. Incorrect parameters types. 96 * <br> 3. Parameter verification failed. 97 * @syscap SystemCapability.ArkUI.ArkUI.Full 98 * @atomicservice 99 * @since 12 100 */ 101 on(type: 'windowSizeChange', callback: Callback<window.Size>): void; 102 103 /** 104 * Unregister the callback of windowSizeChange. 105 * 106 * @param { 'windowSizeChange' } type - The value is fixed at 'windowSizeChange', indicating the window size change event. 107 * @param { Callback<window.Size> } callback - Callback used to return the window size. 108 * @throws { BusinessError } 401 - Parameter error. Possible causes: 109 * <br> 1. Mandatory parameters are left unspecified. 110 * <br> 2. Incorrect parameters types. 111 * <br> 3. Parameter verification failed. 112 * @syscap SystemCapability.ArkUI.ArkUI.Full 113 * @atomicservice 114 * @since 12 115 */ 116 off(type: 'windowSizeChange', callback?: Callback<window.Size>): void; 117 118 /** 119 * Register the callback of rectChange 120 * 121 * @param { 'rectChange' } type - The value is fixed at 'rectChange', indicating the component rect change event. 122 * @param { 'number' } reasons - The reasons of component rect change. 123 * @param { Callback<RectChangeOptions> } callback - Callback used to return the RectChangeOptions. 124 * @throws { BusinessError } 401 - Parameter error. Possible cause: 125 * <br> 1. Mandatory parameters are left unspecified. 126 * <br> 2. Incorrect parameters types. 127 * <br> 3. Parameter verification failed. 128 * @throws { BusinessError } 801 - Capability not supported. Failed to call the API due to limited device capabilities. 129 * @syscap SystemCapability.ArkUI.ArkUI.Full 130 * @atomicservice 131 * @since 14 132 */ 133 on(type: 'rectChange', reasons: number, callback: Callback<RectChangeOptions>): void; 134 135 /** 136 * Unregister the callback of rectChange 137 * 138 * @param { 'rectChange' } type - The value is fixed at 'rectChange', indicating the component rect change event. 139 * @param { Callback<RectChangeOptions> } callback - Callback used to return the RectChangeOptions. 140 * @throws { BusinessError } 401 - Parameter error. Possible cause: 141 * <br> 1. Mandatory parameters are left unspecified. 142 * <br> 2. Incorrect parameters types. 143 * <br> 3. Parameter verification failed. 144 * @throws { BusinessError } 801 - Capability not supported. Failed to call the API due to limited device capabilities. 145 * @syscap SystemCapability.ArkUI.ArkUI.Full 146 * @atomicservice 147 * @since 14 148 */ 149 off(type: 'rectChange', callback?: Callback<RectChangeOptions>): void; 150 151 /** 152 * Hide the non-secure windows. 153 * When called by modal UIExtension and shouldHide == false, the "ohos.permission.ALLOW_SHOW_NON_SECURE_WINDOWS" permission is required. 154 * 155 * @permission ohos.permission.ALLOW_SHOW_NON_SECURE_WINDOWS 156 * @param { boolean } shouldHide - Hide the non-secure windows if true, otherwise means the opposite. 157 * @returns { Promise<void> } - The promise returned by the function. 158 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 159 * @throws { BusinessError } 401 - Parameter error. Possible causes: 160 * <br> 1. Mandatory parameters are left unspecified. 161 * <br> 2. Incorrect parameters types. 162 * <br> 3. Parameter verification failed. 163 * @throws { BusinessError } 1300002 - Abnormal state. Possible causes: 164 * <br> 1. Permission denied. Interface caller does not have permission "ohos.permission.ALLOW_SHOW_NON_SECURE_WINDOWS". 165 * <br> 2. The UIExtension window proxy is abnormal. 166 * @throws { BusinessError } 1300003 - This window manager service works abnormally. 167 * @syscap SystemCapability.ArkUI.ArkUI.Full 168 * @systemapi 169 * @since 12 170 */ 171 hideNonSecureWindows(shouldHide: boolean): Promise<void>; 172 173 /** 174 * Create sub window. 175 * 176 * @param { string } name - window name of sub window. 177 * @param { window.SubWindowOptions } subWindowOptions - options of sub window creation. 178 * @returns { Promise<window.Window> } Promise used to return the subwindow. 179 * @throws { BusinessError } 401 - Parameter error. Possible causes: 180 * <br> 1. Mandatory parameters are left unspecified. 181 * <br> 2. Incorrect parameters types. 182 * <br> 3. Parameter verification failed. 183 * @throws { BusinessError } 801 - Capability not supported. Failed to call the API due to limited device capabilities. 184 * @throws { BusinessError } 1300002 - This window state is abnormal. 185 * @throws { BusinessError } 1300005 - This window proxy is abnormal. 186 * @syscap SystemCapability.ArkUI.ArkUI.Full 187 * @StageModelOnly 188 * @atomicservice 189 * @since 12 190 */ 191 createSubWindowWithOptions(name: string, subWindowOptions: window.SubWindowOptions): Promise<window.Window>; 192 193 /** 194 * Set the watermark flag on the UIExtension window 195 * 196 * @param { boolean } enable - Add water mark flag to the UIExtension window if true, or remove flag if false 197 * @returns { Promise<void> } - The promise returned by the function 198 * @throws { BusinessError } 1300002 - The UIExtension window proxy is abnormal. 199 * @throws { BusinessError } 1300003 - This window manager service works abnormally. 200 * @throws { BusinessError } 1300008 - The display device is abnormal. 201 * @syscap SystemCapability.ArkUI.ArkUI.Full 202 * @systemapi 203 * @since 12 204 */ 205 setWaterMarkFlag(enable: boolean): Promise<void>; 206 207 /** 208 * The properties of the UIExtension window 209 * 210 * @type { WindowProxyProperties } 211 * @syscap SystemCapability.ArkUI.ArkUI.Full 212 * @atomicservice 213 * @since 14 214 */ 215 properties: WindowProxyProperties; 216 } 217 218 /** 219 * Defines the avoid area information. 220 * 221 * @interface AvoidAreaInfo 222 * @syscap SystemCapability.ArkUI.ArkUI.Full 223 * @atomicservice 224 * @since 12 225 */ 226 interface AvoidAreaInfo { 227 /** 228 * Describes the type of avoid area. 229 * 230 * @type { window.AvoidAreaType } 231 * @syscap SystemCapability.ArkUI.ArkUI.Full 232 * @atomicservice 233 * @since 12 234 */ 235 type: window.AvoidAreaType; 236 237 /** 238 * Describes the position and size of avoid area. 239 * 240 * @type { window.AvoidArea } 241 * @syscap SystemCapability.ArkUI.ArkUI.Full 242 * @atomicservice 243 * @since 12 244 */ 245 area: window.AvoidArea; 246 } 247 248 /** 249 * Properties of UIExtension window 250 * 251 * @interface WindowProxyProperties 252 * @syscap SystemCapability.ArkUI.ArkUI.Full 253 * @atomicservice 254 * @since 14 255 * 256 */ 257 interface WindowProxyProperties { 258 /** 259 * The position and size of the UIExtension window 260 * 261 * @type { window.Rect } 262 * @syscap SystemCapability.ArkUI.ArkUI.Full 263 * @atomicservice 264 * @since 14 265 */ 266 uiExtensionHostWindowProxyRect: window.Rect; 267 } 268 269 /** 270 * Defines the reason of component rect change 271 * 272 * @enum { number } 273 * @syscap SystemCapability.ArkUI.ArkUI.Full 274 * @atomicservice 275 * @since 14 276 */ 277 enum RectChangeReason { 278 /** 279 * Host window rect change 280 * 281 * @syscap SystemCapability.ArkUI.ArkUI.Full 282 * @atomicservice 283 * @since 14 284 */ 285 HOST_WINDOW_RECT_CHANGE = 0x0001, 286 } 287 288 /** 289 * Rect change options 290 * 291 * @interface RectChangeOptions 292 * @syscap SystemCapability.ArkUI.ArkUI.Full 293 * @atomicservice 294 * @since 14 295 */ 296 interface RectChangeOptions { 297 /** 298 * Rect of UIExtension Component 299 * 300 * @type { window.Rect } 301 * @syscap SystemCapability.ArkUI.ArkUI.Full 302 * @atomicservice 303 * @since 14 304 */ 305 rect: window.Rect, 306 307 /** 308 * Rect change reason 309 * 310 * @type { RectChangeReason } 311 * @syscap SystemCapability.ArkUI.ArkUI.Full 312 * @atomicservice 313 * @since 14 314 */ 315 reason: RectChangeReason 316 } 317} 318 319export default uiExtension; 320