1/* 2 * Copyright (C) 2021-2022 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 16import type { AsyncCallback } from './basic'; 17import type { Callback } from './basic'; 18 19/** 20 * Accessibility 21 * 22 * @namespace accessibility 23 * @syscap SystemCapability.BarrierFree.Accessibility.Core 24 * @since 7 25 */ 26declare namespace accessibility { 27 /** 28 * The type of the Ability app. 29 * 30 * @type { 'audible' | 'generic' | 'haptic' | 'spoken' | 'visual' } 31 * @syscap SystemCapability.BarrierFree.Accessibility.Core 32 * @since 7 33 */ 34 /** 35 * The type of the Ability app. 36 * 37 * @type { 'audible' | 'generic' | 'haptic' | 'spoken' | 'visual' | 'all' } 38 * @syscap SystemCapability.BarrierFree.Accessibility.Core 39 * @since 9 40 */ 41 type AbilityType = 'audible' | 'generic' | 'haptic' | 'spoken' | 'visual' | 'all'; 42 43 /** 44 * The action that the ability can execute. 45 * 46 * @syscap SystemCapability.BarrierFree.Accessibility.Core 47 * @since 7 48 */ 49 type Action = 'accessibilityFocus' | 'clearAccessibilityFocus' | 'focus' | 'clearFocus' | 'clearSelection' | 50 'click' | 'longClick' | 'cut' | 'copy' | 'paste' | 'select' | 'setText' | 'delete' | 51 'scrollForward' | 'scrollBackward' | 'setSelection'; 52 53 /** 54 * The type of the accessibility event. 55 * windowsChange/windowContentChange/windowStateChange/announcement/notificationChange/textTraversedAtMove 56 * 57 * @syscap SystemCapability.BarrierFree.Accessibility.Core 58 * @since 7 59 */ 60 type EventType = 'accessibilityFocus' | 'accessibilityFocusClear' | 61 'click' | 'longClick' | 'focus' | 'select' | 'hoverEnter' | 'hoverExit' | 62 'textUpdate' | 'textSelectionUpdate' | 'scroll'; 63 64 /** 65 * The change type of the windowsChange event. 66 * It's used when received the {@code windowsChange} event. 67 * 68 * @syscap SystemCapability.BarrierFree.Accessibility.Core 69 * @since 7 70 */ 71 type WindowUpdateType = 'add' | 'remove' | 'bounds' | 'active' | 'focus'; 72 73 /** 74 * The type of the ability state. 75 * 76 * @syscap SystemCapability.BarrierFree.Accessibility.Core 77 * @since 7 78 */ 79 type AbilityState = 'enable' | 'disable' | 'install'; 80 81 /** 82 * The ability that accessibility subsystem support. 83 * touchExplorer: Describes the capability to talkback. 84 * magnification: Describes the capability to request to control the display magnification. 85 * gesturesSimulation: Describes the capability to request to simulate the gesture. 86 * windowContent: Describes the capability to search for the content of the active window. 87 * filterKeyEvents: Describes the capability to request to filter key events. 88 * fingerprintGesture: Describes the capability to request to fingerprint gesture. 89 * 90 * @syscap SystemCapability.BarrierFree.Accessibility.Core 91 * @since 7 92 */ 93 type Capability = 'retrieve' | 'touchGuide' | 'keyEventObserver' | 'zoom' | 'gesture'; 94 95 /** 96 * The granularity of text move. 97 * 98 * @syscap SystemCapability.BarrierFree.Accessibility.Core 99 * @since 7 100 */ 101 type TextMoveUnit = 'char' | 'word' | 'line' | 'page' | 'paragraph'; 102 103 /** 104 * Checks whether accessibility ability is enabled. 105 * 106 * @param { AsyncCallback<boolean> } callback Asynchronous callback interface. 107 * @syscap SystemCapability.BarrierFree.Accessibility.Core 108 * @since 7 109 */ 110 function isOpenAccessibility(callback: AsyncCallback<boolean>): void; 111 112 /** 113 * Checks whether accessibility ability is enabled. 114 * 115 * @param { AsyncCallback<boolean> } callback Asynchronous callback interface. 116 * @returns { Promise<boolean> } Returns {@code true} if the accessibility is enabled; returns {@code false} otherwise. 117 * @syscap SystemCapability.BarrierFree.Accessibility.Core 118 * @since 7 119 */ 120 function isOpenAccessibility(): Promise<boolean>; 121 122 /** 123 * Checks touch browser ability (which is used by talkback) is enabled. 124 * 125 * @param { AsyncCallback<boolean> } callback Asynchronous callback interface. 126 * @syscap SystemCapability.BarrierFree.Accessibility.Vision 127 * @since 7 128 */ 129 function isOpenTouchGuide(callback: AsyncCallback<boolean>): void; 130 131 /** 132 * Checks touch browser ability (which is used by talkback) is enabled. 133 * 134 * @param { AsyncCallback<boolean> } callback Asynchronous callback interface. 135 * @returns { Promise<boolean> } Returns {@code true} if the touch browser is enabled; returns {@code false} otherwise. 136 * @syscap SystemCapability.BarrierFree.Accessibility.Vision 137 * @since 7 138 */ 139 function isOpenTouchGuide(): Promise<boolean>; 140 141 /** 142 * Queries the list of accessibility abilities. 143 * 144 * @param { AbilityType } abilityType The type of the accessibility ability. {@code AbilityType} eg.spoken 145 * @param { AbilityState } stateType The state of the accessibility ability. {@code AbilityState} eg.installed 146 * @param { AsyncCallback<Array<AccessibilityAbilityInfo>> } callback 147 * @syscap SystemCapability.BarrierFree.Accessibility.Core 148 * @since 7 149 * @deprecated since 9 150 */ 151 function getAbilityLists( 152 abilityType: AbilityType, 153 stateType: AbilityState, 154 callback: AsyncCallback<Array<AccessibilityAbilityInfo>> 155 ): void; 156 157 /** 158 * Queries the list of accessibility abilities. 159 * 160 * @param { AbilityType } abilityType The type of the accessibility ability. {@code AbilityType} eg.spoken 161 * @param { AbilityState } stateType The state of the accessibility ability. {@code AbilityState} eg.installed 162 * @returns { Promise<Array<AccessibilityAbilityInfo>> } Returns the list of abilityInfos. 163 * @syscap SystemCapability.BarrierFree.Accessibility.Core 164 * @since 7 165 * @deprecated since 9 166 */ 167 function getAbilityLists(abilityType: AbilityType, stateType: AbilityState): Promise<Array<AccessibilityAbilityInfo>>; 168 169 /** 170 * Queries the list of accessibility abilities. 171 * 172 * @param { AbilityType } abilityType The type of the accessibility ability. {@code AbilityType} eg.spoken 173 * @param { AbilityState } stateType The state of the accessibility ability. {@code AbilityState} eg.installed 174 * @returns { Promise<Array<AccessibilityAbilityInfo>> } Returns the list of abilityInfos. 175 * @throws { BusinessError } 401 - Input parameter error. 176 * @syscap SystemCapability.BarrierFree.Accessibility.Core 177 * @since 9 178 */ 179 function getAccessibilityExtensionList( 180 abilityType: AbilityType, 181 stateType: AbilityState 182 ): Promise<Array<AccessibilityAbilityInfo>>; 183 184 /** 185 * Queries the list of accessibility abilities. 186 * 187 * @param { AbilityType } abilityType The type of the accessibility ability. {@code AbilityType} eg.spoken 188 * @param { AbilityState } stateType The state of the accessibility ability. {@code AbilityState} eg.installed 189 * @param { AsyncCallback<Array<AccessibilityAbilityInfo>> } callback 190 * @throws { BusinessError } 401 - Input parameter error. 191 * @syscap SystemCapability.BarrierFree.Accessibility.Core 192 * @since 9 193 */ 194 function getAccessibilityExtensionList( 195 abilityType: AbilityType, 196 stateType: AbilityState, 197 callback: AsyncCallback<Array<AccessibilityAbilityInfo>> 198 ): void; 199 200 /** 201 * Send accessibility Event. 202 * 203 * @param { EventInfo } event The object of the accessibility {@code EventInfo} . 204 * @param { AsyncCallback<void> } callback Asynchronous callback interface. 205 * @syscap SystemCapability.BarrierFree.Accessibility.Core 206 * @since 7 207 * @deprecated since 9 208 */ 209 function sendEvent(event: EventInfo, callback: AsyncCallback<void>): void; 210 211 /** 212 * Send accessibility Event. 213 * 214 * @param { EventInfo } event The object of the accessibility {@code EventInfo} . 215 * @returns { Promise<void> } Returns {@code true} if success ; returns {@code false} otherwise. 216 * @syscap SystemCapability.BarrierFree.Accessibility.Core 217 * @since 7 218 * @deprecated since 9 219 */ 220 function sendEvent(event: EventInfo): Promise<void>; 221 222 /** 223 * Send accessibility event. 224 * 225 * @param { EventInfo } event The object of the accessibility {@code EventInfo} . 226 * @param { AsyncCallback<void> } callback Asynchronous callback interface. 227 * @throws { BusinessError } 401 - Input parameter error. 228 * @syscap SystemCapability.BarrierFree.Accessibility.Core 229 * @since 9 230 */ 231 function sendAccessibilityEvent(event: EventInfo, callback: AsyncCallback<void>): void; 232 233 /** 234 * Send accessibility event. 235 * 236 * @param { EventInfo } event The object of the accessibility {@code EventInfo} . 237 * @returns { Promise<void> } Returns {@code true} if success ; returns {@code false} otherwise. 238 * @throws { BusinessError } 401 - Input parameter error. 239 * @syscap SystemCapability.BarrierFree.Accessibility.Core 240 * @since 9 241 */ 242 function sendAccessibilityEvent(event: EventInfo): Promise<void>; 243 244 /** 245 * Register the observe of the accessibility state changed. 246 * 247 * @param { 'accessibilityStateChange' } type state event type. 248 * @param { Callback<boolean> } callback Asynchronous callback interface. 249 * @throws { BusinessError } 401 - Input parameter error. 250 * @syscap SystemCapability.BarrierFree.Accessibility.Core 251 * @since 7 252 */ 253 function on(type: 'accessibilityStateChange', callback: Callback<boolean>): void; 254 255 /** 256 * Register the observe of the touchGuide state changed. 257 * 258 * @param { 'touchGuideStateChange' } type state event type. 259 * @param { Callback<boolean> } callback Asynchronous callback interface. 260 * @throws { BusinessError } 401 - Input parameter error. 261 * @syscap SystemCapability.BarrierFree.Accessibility.Vision 262 * @since 7 263 */ 264 function on(type: 'touchGuideStateChange', callback: Callback<boolean>): void; 265 266 /** 267 * Deregister the observe of the accessibility state changed. 268 * 269 * @param { 'accessibilityStateChange' } type state event type 270 * @param { Callback<boolean> } callback Asynchronous callback interface. 271 * @throws { BusinessError } 401 - Input parameter error. 272 * @syscap SystemCapability.BarrierFree.Accessibility.Core 273 * @since 7 274 */ 275 function off(type: 'accessibilityStateChange', callback?: Callback<boolean>): void; 276 277 /** 278 * Deregister the observe of the touchGuide state changed. 279 * 280 * @param { 'touchGuideStateChange' } type state event type 281 * @param { Callback<boolean> } callback Asynchronous callback interface. 282 * @throws { BusinessError } 401 - Input parameter error. 283 * @syscap SystemCapability.BarrierFree.Accessibility.Core 284 * @since 7 285 */ 286 function off(type: 'touchGuideStateChange', callback?: Callback<boolean>): void; 287 288 /** 289 * Get the captions manager. 290 * 291 * @returns { CaptionsManager } Returns the captions manager. 292 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 293 * @since 8 294 */ 295 function getCaptionsManager(): CaptionsManager; 296 297 /** 298 * Indicates the captions manager. 299 * 300 * @typedef CaptionsManager 301 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 302 * @since 8 303 */ 304 interface CaptionsManager { 305 /** 306 * Indicates whether captions are enabled. 307 * 308 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 309 * @since 8 310 */ 311 enabled: boolean; 312 /** 313 * Indicates the style of captions. 314 * 315 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 316 * @since 8 317 */ 318 style: CaptionsStyle; 319 320 /** 321 * Register the observe of the enable state. 322 * 323 * @param { 'enableChange' } type 324 * @param { Callback<boolean> } callback 325 * @throws { BusinessError } 401 - Input parameter error. 326 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 327 * @since 8 328 */ 329 on(type: 'enableChange', callback: Callback<boolean>): void; 330 331 /** 332 * Register the observer of the style. 333 * 334 * @param { 'styleChange' } type 335 * @param { Callback<CaptionsStyle> } callback 336 * @throws { BusinessError } 401 - Input parameter error. 337 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 338 * @since 8 339 */ 340 on(type: 'styleChange', callback: Callback<CaptionsStyle>): void; 341 342 /** 343 * Deregister the observe of the enable state. 344 * 345 * @param { 'enableChange' } type 346 * @param { Callback<boolean> } callback 347 * @throws { BusinessError } 401 - Input parameter error. 348 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 349 * @since 8 350 */ 351 off(type: 'enableChange', callback?: Callback<boolean>): void; 352 353 /** 354 * Deregister the observer of the style. 355 * 356 * @param { 'styleChange' } type 357 * @param { Callback<CaptionsStyle> } callback 358 * @throws { BusinessError } 401 - Input parameter error. 359 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 360 * @since 8 361 */ 362 off(type: 'styleChange', callback?: Callback<CaptionsStyle>): void; 363 } 364 365 /** 366 * Indicates the edge type of the captions font. 367 * 368 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 369 * @since 8 370 */ 371 type CaptionsFontEdgeType = 'none' | 'raised' | 'depressed' | 'uniform' | 'dropShadow'; 372 /** 373 * Indicates the font family of captions. 374 * 375 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 376 * @since 8 377 */ 378 type CaptionsFontFamily = 'default' | 'monospacedSerif' | 'serif' | 379 'monospacedSansSerif' | 'sansSerif' | 'casual' | 'cursive' | 'smallCapitals'; 380 /** 381 * Indicates the style of captions. 382 * 383 * @typedef CaptionsStyle 384 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 385 * @since 8 386 */ 387 interface CaptionsStyle { 388 /** 389 * Indicates the font family of captions. 390 * 391 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 392 * @since 8 393 */ 394 fontFamily: CaptionsFontFamily; 395 /** 396 * Indicates the font scaling of captions. 397 * 398 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 399 * @since 8 400 */ 401 fontScale: number; 402 /** 403 * Indicates the font color of captions. 404 * 405 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 406 * @since 8 407 */ 408 fontColor: number | string; 409 /** 410 * Indicates the edge type of the captions font. 411 * 412 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 413 * @since 8 414 */ 415 fontEdgeType: CaptionsFontEdgeType; 416 /** 417 * Indicates the background color of captions. 418 * 419 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 420 * @since 8 421 */ 422 backgroundColor: number | string; 423 /** 424 * Indicates the window color of captions. 425 * 426 * @syscap SystemCapability.BarrierFree.Accessibility.Hearing 427 * @since 8 428 */ 429 windowColor: number | string; 430 } 431 432 /** 433 * Indicates the info of accessibility. 434 * 435 * @typedef AccessibilityAbilityInfo 436 * @syscap SystemCapability.BarrierFree.Accessibility.Core 437 * @since 7 438 */ 439 interface AccessibilityAbilityInfo { 440 /** 441 * The ability id. 442 * 443 * @syscap SystemCapability.BarrierFree.Accessibility.Core 444 * @since 7 445 */ 446 readonly id: string; 447 448 /* The ability name. 449 * @since 7 450 */ 451 readonly name: string; 452 453 /* The bundle name of the ability. 454 * @since 7 455 */ 456 readonly bundleName: string; 457 458 /* The target bundle name for the observation. 459 * @since 9 460 */ 461 readonly targetBundleNames: Array<string>; 462 463 /** 464 * The type of the ability. 465 * 466 * @syscap SystemCapability.BarrierFree.Accessibility.Core 467 * @since 7 468 */ 469 readonly abilityTypes: Array<AbilityType>; 470 471 /** 472 * The capabilities of the ability. 473 * 474 * @syscap SystemCapability.BarrierFree.Accessibility.Core 475 * @since 7 476 */ 477 readonly capabilities: Array<Capability>; 478 479 /** 480 * The description of the ability. 481 * 482 * @syscap SystemCapability.BarrierFree.Accessibility.Core 483 * @since 7 484 */ 485 readonly description: string; 486 487 /** 488 * The events which the accessibility ability wants to observe. 489 * 490 * @syscap SystemCapability.BarrierFree.Accessibility.Core 491 * @since 7 492 */ 493 readonly eventTypes: Array<EventType>; 494 } 495 496 /** 497 * Indicates the info of events. 498 * 499 * @syscap SystemCapability.BarrierFree.Accessibility.Core 500 * @since 7 501 */ 502 class EventInfo { 503 constructor(jsonObject); 504 /** 505 * The type of an accessibility event. 506 * 507 * @syscap SystemCapability.BarrierFree.Accessibility.Core 508 * @since 7 509 */ 510 type: EventType; 511 512 /** 513 * The type of the window change event. 514 * 515 * @syscap SystemCapability.BarrierFree.Accessibility.Core 516 * @since 7 517 */ 518 windowUpdateType?: WindowUpdateType; 519 520 /** 521 * The bundle name of the target application. 522 * 523 * @syscap SystemCapability.BarrierFree.Accessibility.Core 524 * @since 7 525 */ 526 bundleName: string; 527 528 /** 529 * The type of the event source component,such as button, chart. 530 * 531 * @syscap SystemCapability.BarrierFree.Accessibility.Core 532 * @since 7 533 */ 534 componentType?: string; 535 536 /** 537 * The page id of the event source. 538 * 539 * @syscap SystemCapability.BarrierFree.Accessibility.Core 540 * @since 7 541 */ 542 pageId?: number; 543 544 /** 545 * The accessibility event description. 546 * 547 * @syscap SystemCapability.BarrierFree.Accessibility.Core 548 * @since 7 549 */ 550 description?: string; 551 552 /** 553 * The action that triggers the accessibility event, for example, clicking or focusing a view. 554 * 555 * @syscap SystemCapability.BarrierFree.Accessibility.Core 556 * @since 7 557 */ 558 triggerAction: Action; 559 560 /** 561 * The movement step used for reading texts. 562 * 563 * @syscap SystemCapability.BarrierFree.Accessibility.Core 564 * @since 7 565 */ 566 textMoveUnit?: TextMoveUnit; 567 568 /** 569 * The content list. 570 * 571 * @syscap SystemCapability.BarrierFree.Accessibility.Core 572 * @since 7 573 */ 574 contents?: Array<string>; 575 576 /** 577 * The content changed before. 578 * 579 * @syscap SystemCapability.BarrierFree.Accessibility.Core 580 * @since 7 581 */ 582 lastContent?: string; 583 584 /** 585 * The start index of listed items on the screen. 586 * 587 * @syscap SystemCapability.BarrierFree.Accessibility.Core 588 * @since 7 589 */ 590 beginIndex?: number; 591 592 /** 593 * The index of the current item on the screen. 594 * 595 * @syscap SystemCapability.BarrierFree.Accessibility.Core 596 * @since 7 597 */ 598 currentIndex?: number; 599 600 /** 601 * The end index of listed items on the screen. 602 * 603 * @syscap SystemCapability.BarrierFree.Accessibility.Core 604 * @since 7 605 */ 606 endIndex?: number; 607 608 /** 609 * The total of the items, talkback used it when scroll. 610 * 611 * @syscap SystemCapability.BarrierFree.Accessibility.Core 612 * @since 7 613 */ 614 itemCount?: number; 615 } 616} 617export default accessibility; 618