• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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      * Set events that only need to be handled by the UIExtension provider
209      *
210      * @param { EventFlag } eventFlags - The events to be set.
211      * @returns { Promise<void> } - The promise returned by the function
212      * @throws { BusinessError } 401 - Parameter error. Possible cause:
213      * <br> 1. Mandatory parameters are left unspecified.
214      * <br> 2. Incorrect parameters types.
215      * <br> 3. Parameter verification failed.
216      * @throws { BusinessError } 1300002 - This window state is abnormal.
217      * @throws { BusinessError } 1300003 - This window manager service works abnormally.
218      * @syscap SystemCapability.ArkUI.ArkUI.Full
219      * @atomicservice
220      * @since 18
221      */
222     occupyEvents(eventFlags: number): Promise<void>;
223
224    /**
225     * The properties of the UIExtension window
226     *
227     * @type { WindowProxyProperties }
228     * @syscap SystemCapability.ArkUI.ArkUI.Full
229     * @atomicservice
230     * @since 14
231     */
232    properties: WindowProxyProperties;
233  }
234
235  /**
236   * Gesture event type
237   *
238   * @enum { number }
239   * @syscap SystemCapability.ArkUI.ArkUI.Full
240   * @atomicservice
241   * @since 18
242   */
243  enum EventFlag {
244    /**
245     * None gesture event
246     *
247     * @syscap SystemCapability.ArkUI.ArkUI.Full
248     * @atomicservice
249     * @since 18
250     */
251    EVENT_NONE = 0x00000000,
252    /**
253     * Pan gesture left events
254     *
255     * @syscap SystemCapability.ArkUI.ArkUI.Full
256     * @atomicservice
257     * @since 18
258     */
259    EVENT_PAN_GESTURE_LEFT = 0x00000001,
260    /**
261     * Pan gesture right events
262     *
263     * @syscap SystemCapability.ArkUI.ArkUI.Full
264     * @atomicservice
265     * @since 18
266     */
267    EVENT_PAN_GESTURE_RIGHT = 0x00000002,
268    /**
269     * Pan gesture up events
270     *
271     * @syscap SystemCapability.ArkUI.ArkUI.Full
272     * @atomicservice
273     * @since 18
274     */
275    EVENT_PAN_GESTURE_UP = 0x00000004,
276    /**
277     * Pan gesture down events
278     *
279     * @syscap SystemCapability.ArkUI.ArkUI.Full
280     * @atomicservice
281     * @since 18
282     */
283    EVENT_PAN_GESTURE_DOWN = 0x00000008,
284    /**
285     * Click gesture events
286     *
287     * @syscap SystemCapability.ArkUI.ArkUI.Full
288     * @atomicservice
289     * @since 18
290     */
291    EVENT_CLICK = 0x00000100,
292    /**
293     * Long press gesture events
294     *
295     * @syscap SystemCapability.ArkUI.ArkUI.Full
296     * @atomicservice
297     * @since 18
298     */
299    EVENT_LONG_PRESS = 0x00000200,
300  }
301
302  /**
303   * Defines the avoid area information.
304   *
305   * @interface AvoidAreaInfo
306   * @syscap SystemCapability.ArkUI.ArkUI.Full
307   * @atomicservice
308   * @since 12
309   */
310  interface AvoidAreaInfo {
311    /**
312     * Describes the type of avoid area.
313     *
314     * @type { window.AvoidAreaType }
315     * @syscap SystemCapability.ArkUI.ArkUI.Full
316     * @atomicservice
317     * @since 12
318     */
319    type: window.AvoidAreaType;
320
321    /**
322     * Describes the position and size of avoid area.
323     *
324     * @type { window.AvoidArea }
325     * @syscap SystemCapability.ArkUI.ArkUI.Full
326     * @atomicservice
327     * @since 12
328     */
329    area: window.AvoidArea;
330  }
331
332  /**
333   * Properties of UIExtension window
334   *
335   * @interface WindowProxyProperties
336   * @syscap SystemCapability.ArkUI.ArkUI.Full
337   * @atomicservice
338   * @since 14
339   *
340   */
341  interface WindowProxyProperties {
342    /**
343     * The position and size of the UIExtension window
344     *
345     * @type { window.Rect }
346     * @syscap SystemCapability.ArkUI.ArkUI.Full
347     * @atomicservice
348     * @since 14
349     */
350    uiExtensionHostWindowProxyRect: window.Rect;
351  }
352
353  /**
354   * Defines the reason of component rect change
355   *
356   * @enum { number }
357   * @syscap SystemCapability.ArkUI.ArkUI.Full
358   * @atomicservice
359   * @since 14
360   */
361  enum RectChangeReason {
362    /**
363     * Host window rect change
364     *
365     * @syscap SystemCapability.ArkUI.ArkUI.Full
366     * @atomicservice
367     * @since 14
368     */
369    HOST_WINDOW_RECT_CHANGE = 0x0001,
370  }
371
372  /**
373   * Rect change options
374   *
375   * @interface RectChangeOptions
376   * @syscap SystemCapability.ArkUI.ArkUI.Full
377   * @atomicservice
378   * @since 14
379   */
380  interface RectChangeOptions {
381    /**
382     * Rect of UIExtension Component
383     *
384     * @type { window.Rect }
385     * @syscap SystemCapability.ArkUI.ArkUI.Full
386     * @atomicservice
387     * @since 14
388     */
389    rect: window.Rect,
390
391    /**
392     * Rect change reason
393     *
394     * @type { RectChangeReason }
395     * @syscap SystemCapability.ArkUI.ArkUI.Full
396     * @atomicservice
397     * @since 14
398     */
399    reason: RectChangeReason
400  }
401}
402
403export default uiExtension;
404