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 BasicServicesKit 19 */ 20 21import type { Callback } from './@ohos.base'; 22import type Context from './application/Context'; 23import type { PanelInfo } from './@ohos.selectionInput.SelectionPanel'; 24 25/** 26 * Declares the selectionManager for listening for word selection events and managing word selection panels. 27 * @namespace selectionManager 28 * @syscap SystemCapability.SelectionInput.Selection 29 * @systemapi 30 * @since 20 31 */ 32 33declare namespace selectionManager { 34 /** 35 * Registers a callback to listen for the word selection completion event. 36 * @param { 'selectionCompleted' } type Word selection completion event. 37 * @param { Callback<SelectionInfo> } callback Callback used to listen for the word selection completion 38 * event. 39 * @throws { BusinessError } 33600003 Invalid operation. The selection app is not valid. 40 * @syscap SystemCapability.SelectionInput.Selection 41 * @systemapi 42 * @since 20 43 */ 44 function on(type: 'selectionCompleted', callback: Callback<SelectionInfo>): void; 45 46 /** 47 * Unregisters the callback used to listen for the word selection completion event. 48 * @param { 'selectionCompleted' } type Word selection completion event. 49 * @param { Callback<SelectionInfo> } [callback] (Optional) Callback used to listen for the word selection 50 * completion event. 51 * @syscap SystemCapability.SelectionInput.Selection 52 * @systemapi 53 * @since 20 54 */ 55 function off(type: 'selectionCompleted', callback?: Callback<SelectionInfo>): void; 56 57 /** 58 * Creates a word selection panel. 59 * @param { Context } ctx Context on which the word selection panel depends. 60 * @param { PanelInfo } info Information about the word selection panel. 61 * @returns { Promise<Panel> } Promise used to return the word selection panel. 62 * @throws { BusinessError } 33600001 Selection service exception. 63 * @throws { BusinessError } 33600003 Invalid operation. The selection app is not valid. 64 * @syscap SystemCapability.SelectionInput.Selection 65 * @systemapi 66 * @since 20 67 */ 68 function createPanel(ctx: Context, info: PanelInfo): Promise<Panel>; 69 70 /** 71 * Destroys the word selection panel. 72 * @param { Panel } panel Word selection panel. 73 * @returns { Promise<void> } Promise that returns no value. 74 * @throws { BusinessError } 33600001 Selection service exception. 75 * @syscap SystemCapability.SelectionInput.Selection 76 * @systemapi 77 * @since 20 78 */ 79 function destroyPanel(panel: Panel): Promise<void>; 80 81 /** 82 * Defines the information of a word selection event. 83 * @typedef SelectionInfo 84 * @syscap SystemCapability.SelectionInput.Selection 85 * @systemapi 86 * @since 20 87 */ 88 interface SelectionInfo { 89 /** 90 * Selected text. 91 * @type { string } 92 * @syscap SystemCapability.SelectionInput.Selection 93 * @systemapi 94 * @since 20 95 */ 96 text: string; 97 98 /** 99 * Operation for selecting words. 100 * @type { SelectionType } 101 * @default MOUSE_MOVE 102 * @syscap SystemCapability.SelectionInput.Selection 103 * @systemapi 104 * @since 20 105 */ 106 selectionType: SelectionType; 107 108 /** 109 * X-coordinate of the screen where the word selection starts. 110 * @type { number } 111 * @syscap SystemCapability.SelectionInput.Selection 112 * @systemapi 113 * @since 20 114 */ 115 startDisplayX: number; 116 117 /** 118 * Y-coordinate of the screen where the word selection starts. 119 * @type { number } 120 * @syscap SystemCapability.SelectionInput.Selection 121 * @systemapi 122 * @since 20 123 */ 124 startDisplayY: number; 125 126 /** 127 * X-coordinate of the screen where the word selection ends. 128 * @type { number } 129 * @syscap SystemCapability.SelectionInput.Selection 130 * @systemapi 131 * @since 20 132 */ 133 endDisplayX: number; 134 135 /** 136 * Y-coordinate of the screen where the word selection ends. 137 * @type { number } 138 * @syscap SystemCapability.SelectionInput.Selection 139 * @systemapi 140 * @since 20 141 */ 142 endDisplayY: number; 143 144 /** 145 * X-coordinate of the window where the word selection starts. 146 * @type { number } 147 * @syscap SystemCapability.SelectionInput.Selection 148 * @systemapi 149 * @since 20 150 */ 151 startWindowX: number; 152 153 /** 154 * Y-coordinate of the window where the word selection starts. 155 * @type { number } 156 * @syscap SystemCapability.SelectionInput.Selection 157 * @systemapi 158 * @since 20 159 */ 160 startWindowY: number; 161 162 /** 163 * X-coordinate of the window where the word selection ends. 164 * @type { number } 165 * @syscap SystemCapability.SelectionInput.Selection 166 * @systemapi 167 * @since 20 168 */ 169 endWindowX: number; 170 171 /** 172 * Y-coordinate of the window where the word selection ends. 173 * @type { number } 174 * @syscap SystemCapability.SelectionInput.Selection 175 * @systemapi 176 * @since 20 177 */ 178 endWindowY: number; 179 180 /** 181 * ID of the screen where the window with selected words is located. 182 * @type { number } 183 * @syscap SystemCapability.SelectionInput.Selection 184 * @systemapi 185 * @since 20 186 */ 187 displayID: number; 188 189 /** 190 * ID of the window where words are selected. 191 * @type { number } 192 * @syscap SystemCapability.SelectionInput.Selection 193 * @systemapi 194 * @since 20 195 */ 196 windowID: number; 197 198 /** 199 * Bundle name of the application where words are selected. 200 * @type { string } 201 * @syscap SystemCapability.SelectionInput.Selection 202 * @systemapi 203 * @since 20 204 */ 205 bundleName: string; 206 } 207 208 /** 209 * Defines a word selection panel. 210 * @typedef Panel 211 * @syscap SystemCapability.SelectionInput.Selection 212 * @systemapi 213 * @since 20 214 */ 215 interface Panel { 216 /** 217 * Sets the content to be displayed in the panel. 218 * @param { string } path Path of the content to be displayed. 219 * @returns { Promise<void> } Promise that returns no value. 220 * @throws { BusinessError } 33600001 Selection service exception. 221 * @throws { BusinessError } 33600002 This selection window has been destroyed. 222 * @syscap SystemCapability.SelectionInput.Selection 223 * @systemapi 224 * @since 20 225 */ 226 setUiContent(path: string): Promise<void>; 227 228 /** 229 * Shows this word selection panel. 230 * @returns { Promise<void> } Promise that returns no value. 231 * @throws { BusinessError } 33600001 Selection service exception. 232 * @throws { BusinessError } 33600002 This selection window has been destroyed. 233 * @syscap SystemCapability.SelectionInput.Selection 234 * @systemapi 235 * @since 20 236 */ 237 show(): Promise<void>; 238 239 /** 240 * Hides this word selection panel. 241 * @returns { Promise<void> } Promise that returns no value. 242 * @throws { BusinessError } 33600001 Selection service exception. 243 * @throws { BusinessError } 33600002 This selection window has been destroyed. 244 * @syscap SystemCapability.SelectionInput.Selection 245 * @systemapi 246 * @since 20 247 */ 248 hide(): Promise<void>; 249 250 /** 251 * Moves the word selection panel by dragging. 252 * @returns { Promise<void> } Promise that returns no value. 253 * @throws { BusinessError } 33600001 Selection service exception. 254 * @throws { BusinessError } 33600002 This selection window has been destroyed. 255 * @syscap SystemCapability.SelectionInput.Selection 256 * @systemapi 257 * @since 20 258 */ 259 startMoving(): Promise<void>; 260 261 /** 262 * Moves the word selection panel to the specified coordinates on the screen. 263 * @param { number } x X-coordinate on the screen. 264 * @param { number } y Y-coordinate on the screen. 265 * @returns { Promise<void> } Promise that returns no value. 266 * @throws { BusinessError } 33600001 Selection service exception. 267 * @throws { BusinessError } 33600002 This selection window has been destroyed. 268 * @syscap SystemCapability.SelectionInput.Selection 269 * @systemapi 270 * @since 20 271 */ 272 moveTo(x: number, y: number): Promise<void>; 273 274 /** 275 * Registers a callback to listen for the destroy event of the word selection panel. 276 * @param { 'destroyed' } type Destroy event of the word selection panel. 277 * @param { Callback<void> } callback Callback used to listen for the destroy event of the word selection 278 * panel. 279 * @syscap SystemCapability.SelectionInput.Selection 280 * @systemapi 281 * @since 20 282 */ 283 on(type: 'destroyed', callback: Callback<void>): void; 284 285 /** 286 * Unregisters the callback used to listen for the destroy event of the word selection panel. 287 * @param { 'destroyed' } type Destroy event of the word selection panel. 288 * @param { Callback<void> } [callback] Callback used to listen for the destroy event of the word 289 * selection panel. 290 * @syscap SystemCapability.SelectionInput.Selection 291 * @systemapi 292 * @since 20 293 */ 294 off(type: 'destroyed', callback?: Callback<void>): void; 295 296 /** 297 * Registers a callback to listen for the hide event of the word selection panel. 298 * @param { 'hidden' } type Hide event of the word selection panel. 299 * @param { Callback<void> } callback Callback used to listen for the hide event of the word selection 300 * panel. 301 * @syscap SystemCapability.SelectionInput.Selection 302 * @systemapi 303 * @since 20 304 */ 305 on(type: 'hidden', callback: Callback<void>): void; 306 307 /** 308 * Unregisters the callback used to listen for the hide event of the word selection panel. 309 * @param { 'hidden' } type Hide event of the word selection panel. 310 * @param { Callback<void> } [callback] Callback used to listen for the hide event of the word selection 311 * panel. 312 * @syscap SystemCapability.SelectionInput.Selection 313 * @systemapi 314 * @since 20 315 */ 316 off(type: 'hidden', callback?: Callback<void>): void; 317 } 318 319 /** 320 * Enumerates the operations for selecting words. 321 * @enum { number } 322 * @syscap SystemCapability.SelectionInput.Selection 323 * @systemapi 324 * @since 20 325 */ 326 enum SelectionType { 327 /** 328 * Move the cursor to select words. 329 * @syscap SystemCapability.SelectionInput.Selection 330 * @systemapi 331 * @since 20 332 */ 333 MOUSE_MOVE = 1, 334 335 /** 336 * Double-click to select words. 337 * @syscap SystemCapability.SelectionInput.Selection 338 * @systemapi 339 * @since 20 340 */ 341 DOUBLE_CLICK = 2, 342 343 /** 344 * Triple-click to select words. 345 * @syscap SystemCapability.SelectionInput.Selection 346 * @systemapi 347 * @since 20 348 */ 349 TRIPLE_CLICK = 3 350 } 351} 352 353export default selectionManager;