1/* 2 * Copyright (c) 2025 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 21import type BaseContext from './application/BaseContext'; 22import type image from './@ohos.multimedia.image'; 23import type Want from './@ohos.app.ability.Want'; 24import type { Callback } from './@ohos.base'; 25 26/** 27 * Floating ball 28 * 29 * @namespace floatingBall 30 * @syscap SystemCapability.Window.SessionManager 31 * @since 20 32 */ 33declare namespace floatingBall { 34 /** 35 * If floating ball enabled in current device. 36 * 37 * @returns { boolean } true if floating ball enabled, otherwise false. 38 * @syscap SystemCapability.Window.SessionManager 39 * @since 20 40 */ 41 function isFloatingBallEnabled(): boolean; 42 43 /** 44 * Create floating ball controller 45 * 46 * @param { FloatingBallConfiguration } config - Params for floating ball controller creation. 47 * The config must be valid, the context in config should not be null. 48 * @returns { Promise<FloatingBallController> } - The promise returned by the function. 49 * @throws { BusinessError } 801 - Capability not supported. 50 * Failed to call the API due to limited device capabilities. 51 * @throws { BusinessError } 1300019 - Wrong parameters for operating the floating ball. 52 * @throws { BusinessError } 1300023 - Floating ball internal error. 53 * @syscap SystemCapability.Window.SessionManager 54 * @since 20 55 */ 56 function create(config: FloatingBallConfiguration): Promise<FloatingBallController>; 57 58 /** 59 * FloatingBallConfiguration 60 * 61 * @interface FloatingBallConfiguration 62 * @syscap SystemCapability.Window.SessionManager 63 * @since 20 64 */ 65 interface FloatingBallConfiguration { 66 /** 67 * Indicates window context. 68 * 69 * @type { BaseContext } 70 * @syscap SystemCapability.Window.SessionManager 71 * @since 20 72 */ 73 context: BaseContext; 74 } 75 76 /** 77 * FloatingBallController 78 * 79 * @interface FloatingBallController 80 * @syscap SystemCapability.Window.SessionManager 81 * @since 20 82 */ 83 interface FloatingBallController { 84 /** 85 * Start floating ball 86 * 87 * @permission ohos.permission.USE_FLOAT_BALL 88 * @param { FloatingBallParams } params - Params for floating ball start. 89 * @returns { Promise<void> } - The promise returned by the function. 90 * @throws { BusinessError } 201 - Permission verification failed, usually returned by VerifyAccessToken. 91 * @throws { BusinessError } 1300019 - Wrong parameters for operating the floating ball. 92 * @throws { BusinessError } 1300020 - Failed to create the floating ball window. 93 * @throws { BusinessError } 1300021 - Failed to start multiple floating ball windows. 94 * @throws { BusinessError } 1300022 - Repeated floating ball operation. 95 * @throws { BusinessError } 1300023 - Floating ball internal error. 96 * @throws { BusinessError } 1300024 - The floating ball window state is abnormal. 97 * @throws { BusinessError } 1300025 - The floating ball state does not support this operation. 98 * @syscap SystemCapability.Window.SessionManager 99 * @since 20 100 */ 101 startFloatingBall(params: FloatingBallParams): Promise<void>; 102 103 /** 104 * Update floating ball 105 * 106 * @param { FloatingBallParams } params - Params for floating ball update. 107 * @returns { Promise<void> } - The promise returned by the function. 108 * @throws { BusinessError } 1300002 - This window state is abnormal. 109 * @throws { BusinessError } 1300003 - This window manager service works abnormally. 110 * @throws { BusinessError } 1300004 - Unauthorized operation. 111 * @throws { BusinessError } 1300019 - Wrong parameters for operating the floating ball. 112 * @throws { BusinessError } 1300023 - Floating ball internal error. 113 * @throws { BusinessError } 1300024 - The floating ball window state is abnormal. 114 * @throws { BusinessError } 1300025 - The floating ball state does not support this operation. 115 * @throws { BusinessError } 1300027 - When updating the floating ball, the template type cannot be changed. 116 * @throws { BusinessError } 1300028 - Updating static template-based floating balls is not supported. 117 * @syscap SystemCapability.Window.SessionManager 118 * @since 20 119 */ 120 updateFloatingBall(params: FloatingBallParams): Promise<void>; 121 122 /** 123 * Stop floating ball. 124 * 125 * @returns { Promise<void> } - The promise returned by the function. 126 * @throws { BusinessError } 1300022 - Repeated floating ball operation. 127 * @throws { BusinessError } 1300023 - Floating ball internal error. 128 * @throws { BusinessError } 1300024 - The floating ball window state is abnormal. 129 * @syscap SystemCapability.Window.SessionManager 130 * @since 20 131 */ 132 stopFloatingBall(): Promise<void>; 133 134 /** 135 * Register floating ball lifecycle event listener. 136 * 137 * @param { 'stateChange' } type - Registration type, floating ball lifecycle state change, 'stateChange'. 138 * @param { Callback<FloatingBallState> } callback - Used to handle {'stateChange'} command. 139 * @throws { BusinessError } 1300019 - Wrong parameters for operating the floating ball. 140 * @throws { BusinessError } 1300022 - Repeated floating ball operation. 141 * @throws { BusinessError } 1300023 - Floating ball internal error. 142 * @throws { BusinessError } 1300024 - The floating ball window state is abnormal. 143 * @syscap SystemCapability.Window.SessionManager 144 * @since 20 145 */ 146 on(type: 'stateChange', callback: Callback<FloatingBallState>): void; 147 148 /** 149 * Unregister floating ball lifecycle event listener. 150 * 151 * @param { 'stateChange' } type - Used to unregister listener for {'stateChange'} command. 152 * @param { Callback<FloatingBallState> } [callback] - Indicates the callback function. 153 * @throws { BusinessError } 1300019 - Wrong parameters for operating the floating ball. 154 * @throws { BusinessError } 1300023 - Floating ball internal error. 155 * @throws { BusinessError } 1300024 - The floating ball window state is abnormal. 156 * @syscap SystemCapability.Window.SessionManager 157 * @since 20 158 */ 159 off(type: 'stateChange', callback?: Callback<FloatingBallState>): void; 160 161 /** 162 * Register floating ball click event listener. 163 * 164 * @param { 'click' } type - Registration type, user click event, 'click'. 165 * @param { Callback<void> } callback - Used to handle {'click'} command. 166 * @throws { BusinessError } 1300019 - Wrong parameters for operating the floating ball. 167 * @throws { BusinessError } 1300022 - Repeated floating ball operation. 168 * @throws { BusinessError } 1300023 - Floating ball internal error. 169 * @throws { BusinessError } 1300024 - The floating ball window state is abnormal. 170 * @syscap SystemCapability.Window.SessionManager 171 * @since 20 172 */ 173 on(type: 'click', callback: Callback<void>): void; 174 175 /** 176 * Unregister floating ball click event listener. 177 * 178 * @param { 'click' } type - Used to unregister listener for {'click'} command. 179 * @param { Callback<void> } [callback] - Indicates the callback function. 180 * @throws { BusinessError } 1300019 - Wrong parameters for operating the floating ball. 181 * @throws { BusinessError } 1300023 - Floating ball internal error. 182 * @throws { BusinessError } 1300024 - The floating ball window state is abnormal. 183 * @syscap SystemCapability.Window.SessionManager 184 * @since 20 185 */ 186 off(type: 'click', callback?: Callback<void>): void; 187 188 /** 189 * Get the info of floating ball window. 190 * 191 * @returns { Promise<FloatingBallWindowInfo> } - The promise used to return the floating ball window info. 192 * @throws { BusinessError } 1300002 - This window state is abnormal. 193 * @throws { BusinessError } 1300003 - This window manager service works abnormally. 194 * @throws { BusinessError } 1300004 - Unauthorized operation. 195 * @throws { BusinessError } 1300023 - Floating ball internal error. 196 * @throws { BusinessError } 1300024 - The floating ball window state is abnormal. 197 * @throws { BusinessError } 1300025 - The floating ball state does not support this operation. 198 * @syscap SystemCapability.Window.SessionManager 199 * @since 20 200 */ 201 getFloatingBallWindowInfo(): Promise<FloatingBallWindowInfo>; 202 203 /** 204 * Restore main window for floating ball creatorBundle. 205 * 206 * @permission ohos.permission.USE_FLOAT_BALL 207 * @param { Want } want - Params for floating ball restoration. 208 * @returns { Promise<void> } - The promise returned by the function. 209 * @throws { BusinessError } 201 - Permission verification failed, usually returned by VerifyAccessToken. 210 * @throws { BusinessError } 1300002 - This window state is abnormal. 211 * @throws { BusinessError } 1300003 - This window manager service works abnormally. 212 * @throws { BusinessError } 1300004 - Unauthorized operation. 213 * @throws { BusinessError } 1300019 - Wrong parameters for operating the floating ball. 214 * @throws { BusinessError } 1300023 - Floating ball internal error. 215 * @throws { BusinessError } 1300024 - The floating ball window state is abnormal. 216 * @throws { BusinessError } 1300025 - The floating ball state does not support this operation. 217 * @throws { BusinessError } 1300026 - Failed to restore the main window. 218 * @syscap SystemCapability.Window.SessionManager 219 * @since 20 220 */ 221 restoreMainWindow(want: Want): Promise<void>; 222 } 223 224 /** 225 * The option of floating ball 226 * 227 * @interface FloatingBallParams 228 * @syscap SystemCapability.Window.SessionManager 229 * @since 20 230 */ 231 interface FloatingBallParams { 232 /** 233 * The template of floating ball. 234 * 235 * @type { FloatingBallTemplate } 236 * @syscap SystemCapability.Window.SessionManager 237 * @since 20 238 */ 239 template: FloatingBallTemplate; 240 241 /** 242 * The title of floating ball. 243 * 244 * @type { string } 245 * @syscap SystemCapability.Window.SessionManager 246 * @since 20 247 */ 248 title: string; 249 250 /** 251 * The content of floating ball. 252 * 253 * @type { ?string } 254 * @syscap SystemCapability.Window.SessionManager 255 * @since 20 256 */ 257 content?: string; 258 259 /** 260 * The backgroundColor of floating ball. 261 * 262 * @type { ?string } 263 * @syscap SystemCapability.Window.SessionManager 264 * @since 20 265 */ 266 backgroundColor?: string; 267 268 /** 269 * The icon of floating ball. 270 * 271 * @type { ?image.PixelMap } 272 * @syscap SystemCapability.Window.SessionManager 273 * @since 20 274 */ 275 icon?: image.PixelMap; 276 } 277 278 /** 279 * Enum for FloatingBall state type. 280 * 281 * @enum { number } 282 * @syscap SystemCapability.Window.SessionManager 283 * @since 20 284 */ 285 enum FloatingBallState { 286 /** 287 * FloatingBall window started. 288 * 289 * @syscap SystemCapability.Window.SessionManager 290 * @since 20 291 */ 292 STARTED = 1, 293 294 /** 295 * FloatingBall window stopped. 296 * 297 * @syscap SystemCapability.Window.SessionManager 298 * @since 20 299 */ 300 STOPPED = 2 301 } 302 303 /** 304 * Enum for FloatingBall template type. 305 * 306 * @enum { number } 307 * @syscap SystemCapability.Window.SessionManager 308 * @since 20 309 */ 310 enum FloatingBallTemplate { 311 /** 312 * Static layout, support icon and title. 313 * 314 * @syscap SystemCapability.Window.SessionManager 315 * @since 20 316 */ 317 STATIC = 1, 318 319 /** 320 * Normal layout, support title and content. 321 * 322 * @syscap SystemCapability.Window.SessionManager 323 * @since 20 324 */ 325 NORMAL = 2, 326 327 /** 328 * Emphatic layout, support icon, title, and content. 329 * 330 * @syscap SystemCapability.Window.SessionManager 331 * @since 20 332 */ 333 EMPHATIC = 3, 334 335 /** 336 * Simple layout, support title with 2-lines display. 337 * 338 * @syscap SystemCapability.Window.SessionManager 339 * @since 20 340 */ 341 SIMPLE = 4 342 } 343 344 /** 345 * The info of floating ball window. 346 * 347 * @interface FloatingBallWindowInfo 348 * @syscap SystemCapability.Window.SessionManager 349 * @since 20 350 */ 351 interface FloatingBallWindowInfo { 352 /** 353 * Indicates target window id. 354 * 355 * @type { number } 356 * @readonly 357 * @syscap SystemCapability.Window.SessionManager 358 * @since 20 359 */ 360 readonly windowId: number; 361 } 362} 363 364export default floatingBall; 365