1/* 2 * Copyright (c) 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 16/** 17 * @file 18 * @kit ArkUI 19 */ 20 21import { AsyncCallback, ErrorCallback } from './@ohos.base'; 22import image from './@ohos.multimedia.image'; 23 24 /** 25 * Declares the screenshot APIs. 26 * 27 * @namespace screenshot 28 * @syscap SystemCapability.WindowManager.WindowManager.Core 29 * @atomicservice 30 * @since 12 31 */ 32declare namespace screenshot { 33 /** 34 * Takes a screenshot and saves it as a PixelMap object. 35 * 36 * @permission ohos.permission.CAPTURE_SCREEN 37 * @param { ScreenshotOptions } options Screenshot options, which consist of screenRect, imageSize, and rotation. You need to set these parameters 38 * @param { AsyncCallback<image.PixelMap> } callback Callback used to return a PixelMap object. 39 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 40 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 41 * <br>2.Incorrect parameter types. 42 * @syscap SystemCapability.WindowManager.WindowManager.Core 43 * @systemapi Hide this for inner system use. 44 * @since 7 45 */ 46 /** 47 * Takes a screenshot and saves it as a PixelMap object. 48 * 49 * @permission ohos.permission.CAPTURE_SCREEN 50 * @param { ScreenshotOptions } options - Screenshot options, which consist of screenRect, imageSize, and rotation. You need to set these parameters 51 * @param { AsyncCallback<image.PixelMap> } callback - Callback used to return a PixelMap object. 52 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 53 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 54 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 55 * <br>2.Incorrect parameter types. 56 * @throws { BusinessError } 1400001 - Invalid display or screen. 57 * @syscap SystemCapability.WindowManager.WindowManager.Core 58 * @systemapi Hide this for inner system use. 59 * @since 11 60 */ 61 function save(options: ScreenshotOptions, callback: AsyncCallback<image.PixelMap>): void; 62 63 /** 64 * Screen capture, supporting HDR screenshots when there is HDR content. 65 * 66 * @permission ohos.permission.CAPTURE_SCREEN 67 * @param { HdrScreenshotOptions } [options] - Screenshot parameters. 68 * @returns { Promise<Array<image.PixelMap>> } Promise used to return a PixelMap array. When HDR content is available, 69 * return two PixelMap objects: the first one as SDR and the second one as HDR. When no HDR content is available, only return one SDR PixelMap object. 70 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 71 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 72 * @throws { BusinessError } 801 - Capability not supported. Failed to call the API due to limited device capabilities. 73 * @throws { BusinessError } 1400001 - Invalid display or screen. 74 * @throws { BusinessError } 1400003 - This display manager service works abnormally. 75 * @throws { BusinessError } 1400004 - Parameter error. Possible cause: 1.Invalid parameter range. 76 * @syscap SystemCapability.Window.SessionManager 77 * @systemapi Hide this for inner system use. 78 * @since 20 79 */ 80 function saveHdrPicture(options?: HdrScreenshotOptions): Promise<Array<image.PixelMap>>; 81 82 /** 83 * Takes a screenshot and saves it as a PixelMap object. 84 * 85 * @permission ohos.permission.CAPTURE_SCREEN 86 * @param { AsyncCallback<image.PixelMap> } callback Callback used to return a PixelMap object. 87 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 88 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 89 * @syscap SystemCapability.WindowManager.WindowManager.Core 90 * @systemapi Hide this for inner system use. 91 * @since 7 92 */ 93 function save(callback: AsyncCallback<image.PixelMap>): void; 94 95 /** 96 * Takes a screenshot and saves it as a PixelMap object. 97 * 98 * @permission ohos.permission.CAPTURE_SCREEN 99 * @param { ScreenshotOptions } options Screenshot options, which consist of screenRect, imageSize, and rotation. You need to set these parameters 100 * @returns { Promise<image.PixelMap> } Promise used to return a PixelMap object. 101 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 102 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 103 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 104 * <br>2.Incorrect parameter types. 105 * @syscap SystemCapability.WindowManager.WindowManager.Core 106 * @systemapi Hide this for inner system use. 107 * @since 7 108 */ 109 function save(options?: ScreenshotOptions): Promise<image.PixelMap>; 110 111 /** 112 * Takes a capture and return as a PixelMap object. 113 * 114 * @permission ohos.permission.CUSTOM_SCREEN_CAPTURE 115 * @param { CaptureOption } options which consist of CaptureOption. 116 * @returns { Promise<image.PixelMap> } Promise used to return a PixelMap object. 117 * @throws { BusinessError } 201 - Permission verification failed. The application does not have the permission required to call the API. 118 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 119 * 2.Incorrect parameter types. 120 * @throws { BusinessError } 801 - Capability not supported on this device. 121 * @throws { BusinessError } 1400003 - This display manager service works abnormally. 122 * @syscap SystemCapability.WindowManager.WindowManager.Core 123 * @atomicservice 124 * @since 14 125 */ 126 function capture(options?: CaptureOption): Promise<image.PixelMap>; 127 128 /** 129 * Takes a screenshot and picks it as a PickInfo object. 130 * 131 * @returns { Promise<PickInfo> } Promise used to return a PickInfo object. 132 * @throws { BusinessError } 801 - Capability not supported on this device. 133 * @throws { BusinessError } 1400003 - This display manager service works abnormally. 134 * @syscap SystemCapability.WindowManager.WindowManager.Core 135 * @atomicservice 136 * @since 12 137 */ 138 function pick(): Promise<PickInfo>; 139 140 /** 141 * Describes the region of the screen to pick info. 142 * 143 * @interface PickInfo 144 * @syscap SystemCapability.WindowManager.WindowManager.Core 145 * @atomicservice 146 * @since 12 147 */ 148 interface PickInfo { 149 /** 150 * the region of the screen to capture. 151 * 152 * @type { Rect } 153 * @syscap SystemCapability.WindowManager.WindowManager.Core 154 * @atomicservice 155 * @since 12 156 */ 157 pickRect: Rect; 158 159 /** 160 * the region of the screen to capture pixelMap. 161 * 162 * @type { image.PixelMap } 163 * @syscap SystemCapability.WindowManager.WindowManager.Core 164 * @atomicservice 165 * @since 12 166 */ 167 pixelMap: image.PixelMap; 168 } 169 170 /** 171 * Describes the region of the screen to capture. 172 * 173 * @interface Rect 174 * @syscap SystemCapability.WindowManager.WindowManager.Core 175 * @atomicservice 176 * @since 12 177 */ 178 interface Rect { 179 /** 180 * The X-axis coordinate of the upper left vertex of the rectangle. 181 * 182 * @type { number } 183 * @syscap SystemCapability.WindowManager.WindowManager.Core 184 * @atomicservice 185 * @since 12 186 */ 187 left: number; 188 189 /** 190 * The Y-axis coordinate of the upper left vertex of the rectangle. 191 * 192 * @type { number } 193 * @syscap SystemCapability.WindowManager.WindowManager.Core 194 * @atomicservice 195 * @since 12 196 */ 197 top: number; 198 199 /** 200 * Width of the rectangle. 201 * 202 * @type { number } 203 * @syscap SystemCapability.WindowManager.WindowManager.Core 204 * @atomicservice 205 * @since 12 206 */ 207 width: number; 208 209 /** 210 * Height of the rectangle. 211 * 212 * @type { number } 213 * @syscap SystemCapability.WindowManager.WindowManager.Core 214 * @atomicservice 215 * @since 12 216 */ 217 height: number; 218 } 219 220 /** 221 * Describes the size of the screen region to capture. 222 * 223 * @interface Size 224 * @syscap SystemCapability.WindowManager.WindowManager.Core 225 * @systemapi Hide this for inner system use. 226 * @since 7 227 */ 228 interface Size { 229 /** 230 * Defines the width property. 231 * 232 * @type { number } 233 * @syscap SystemCapability.WindowManager.WindowManager.Core 234 * @systemapi Hide this for inner system use. 235 * @since 7 236 */ 237 width: number; 238 239 /** 240 * Defines the height property. 241 * 242 * @type { number } 243 * @syscap SystemCapability.WindowManager.WindowManager.Core 244 * @systemapi Hide this for inner system use. 245 * @since 7 246 */ 247 height: number; 248 } 249 250 /** 251 * Describes capture options. 252 * 253 * @interface CaptureOption 254 * @syscap SystemCapability.WindowManager.WindowManager.Core 255 * @atomicservice 256 * @since 14 257 */ 258 interface CaptureOption { 259 /** 260 * ID of the screen to be captured. 261 * 262 * @type { ?number } 263 * @syscap SystemCapability.WindowManager.WindowManager.Core 264 * @atomicservice 265 * @since 14 266 */ 267 displayId?: number; 268 } 269 270 /** 271 * Describes screenshot options. 272 * 273 * @interface ScreenshotOptions 274 * @syscap SystemCapability.WindowManager.WindowManager.Core 275 * @systemapi Hide this for inner system use. 276 * @since 7 277 */ 278 interface ScreenshotOptions { 279 /** 280 * Region of the screen to capture. If this parameter is null, the full screen will be captured. 281 * 282 * @type { ?Rect } 283 * @syscap SystemCapability.WindowManager.WindowManager.Core 284 * @systemapi Hide this for inner system use. 285 * @since 7 286 */ 287 screenRect?: Rect; 288 /** 289 * Region of the screen to capture. If this parameter is null, the full screen will be captured. 290 * 291 * @type { ?Size } 292 * @syscap SystemCapability.WindowManager.WindowManager.Core 293 * @systemapi Hide this for inner system use. 294 * @since 7 295 */ 296 imageSize?: Size; 297 /** 298 * Rotation angle of the screenshot. The value can be 0, 90, 180, or 270. The default value is 0. 299 * 300 * @type { ?number } 301 * @syscap SystemCapability.WindowManager.WindowManager.Core 302 * @systemapi Hide this for inner system use. 303 * @since 7 304 */ 305 rotation?: number; 306 /** 307 * ID of the screen to be captured. 308 * 309 * @type { ?number } 310 * @syscap SystemCapability.WindowManager.WindowManager.Core 311 * @systemapi Hide this for inner system use. 312 * @since 8 313 */ 314 displayId?: number; 315 /** 316 * The capture action is need notification. 317 * 318 * @type { ?boolean } 319 * @syscap SystemCapability.WindowManager.WindowManager.Core 320 * @systemapi Hide this for inner system use. 321 * @since 14 322 */ 323 isNotificationNeeded?: boolean; 324 /** 325 * The capture action is need take screenshots of all displays on this screen. 326 * 327 * @type { ?boolean } 328 * @syscap SystemCapability.WindowManager.WindowManager.Core 329 * @systemapi Hide this for inner system use. 330 * @since 20 331 */ 332 isCaptureFullOfScreen?: boolean; 333 } 334 335 /** 336 * Describes hdr screenshot options. 337 * 338 * @interface HdrScreenshotOptions 339 * @syscap SystemCapability.Window.SessionManager 340 * @systemapi Hide this for inner system use. 341 * @since 20 342 */ 343 interface HdrScreenshotOptions { 344 /** 345 * ID of the screen to be captured. 346 * 347 * @type { ?number } 348 * @syscap SystemCapability.Window.SessionManager 349 * @systemapi Hide this for inner system use. 350 * @since 20 351 */ 352 displayId?: number; 353 /** 354 * The capture action is need notification. 355 * 356 * @type { ?boolean } 357 * @syscap SystemCapability.Window.SessionManager 358 * @systemapi Hide this for inner system use. 359 * @since 20 360 */ 361 isNotificationNeeded?: boolean; 362 /** 363 * The capture action is need take screenshots of all displays on this screen. 364 * 365 * @type { ?boolean } 366 * @syscap SystemCapability.Window.SessionManager 367 * @systemapi Hide this for inner system use. 368 * @since 20 369 */ 370 isCaptureFullOfScreen?: boolean; 371 } 372} 373 374export default screenshot; 375