• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.display (Display) (System API)
2<!--Kit: ArkUI-->
3<!--Subsystem: Window-->
4<!--Owner: @oh_wangxk; @logn-->
5<!--Designer: @hejunfei1991-->
6<!--Tester: @qinliwen0417-->
7<!--Adviser: @ge-yafang-->
8
9The Display module provides APIs for managing displays, such as obtaining information about the default display, obtaining information about all displays, and listening for the addition and removal of displays.
10
11> **NOTE**
12>
13> - The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
14>
15> - This topic describes only system APIs provided by the module. For details about its public APIs, see [@ohos.display (Display)](js-apis-display.md).
16
17## Modules to Import
18
19```ts
20import { display } from '@kit.ArkUI';
21```
22
23## display.hasPrivateWindow<sup>9+</sup>
24
25hasPrivateWindow(displayId: number): boolean
26
27Checks whether there is a visible privacy window on a display. The privacy window can be set by calling [setWindowPrivacyMode()](arkts-apis-window-Window.md#setwindowprivacymode9). The content in the privacy window cannot be captured or recorded.
28
29**System API**: This is a system API.
30
31**System capability**: SystemCapability.WindowManager.WindowManager.Core
32
33**Parameters**
34
35| Name| Type                     | Mandatory| Description      |
36| ------ | ------------------------- | ---- |----------|
37| displayId    | number                    | Yes  | ID of the display. The value must be an integer greater than or equal to 0.|
38
39**Return value**
40
41| Type                            | Description                                                                   |
42| -------------------------------- |-----------------------------------------------------------------------|
43|boolean | Whether there is a visible privacy window on the display. **true** if yes, **false** otherwise.|
44
45**Error codes**
46
47For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md).
48
49| ID| Error Message|
50| ------- | -------------------------------------------- |
51| 202     | Permission verification failed. A non-system application calls a system API.|
52| 401     | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.|
53| 1400003 | This display manager service works abnormally. |
54
55**Example**
56
57```ts
58import { display } from '@kit.ArkUI';
59
60let displayClass: display.Display | null = null;
61try {
62  displayClass = display.getDefaultDisplaySync();
63
64  let ret: boolean = true;
65  try {
66    ret = display.hasPrivateWindow(displayClass.id);
67  } catch (exception) {
68    console.error('Failed to check has privateWindow or not. Code: ' + JSON.stringify(exception));
69  }
70  if (ret == undefined) {
71    console.log("Failed to check has privateWindow or not.");
72  }
73  if (ret) {
74    console.log("There has privateWindow.");
75  } else if (!ret) {
76    console.log("There has no privateWindow.");
77  }
78} catch (exception) {
79  console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception));
80}
81```
82
83## display.on('privateModeChange')<sup>10+</sup>
84
85on(type: 'privateModeChange', callback: Callback&lt;boolean&gt;): void
86
87Subscribes to privacy mode changes of this display. When there is a privacy window in the foreground of the display, the display is in privacy mode, and the content in the privacy window cannot be captured or recorded.
88
89**System API**: This is a system API.
90
91**System capability**: SystemCapability.WindowManager.WindowManager.Core
92
93**Parameters**
94
95| Name  | Type                                      | Mandatory| Description                                                   |
96| -------- |------------------------------------------| ---- | ------------------------------------------------------- |
97| type     | string                                   | Yes  | Event type. The value is fixed at **'privateModeChange'**, indicating that the privacy mode of the display is changed.|
98| callback | Callback&lt;boolean&gt; | Yes  | Callback used to return whether the privacy mode of the display is changed. **true** if changed, **false** otherwise.|
99
100**Error codes**
101
102For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
103
104| ID| Error Message|
105| ------- | ----------------------- |
106| 202     | Permission verification failed. A non-system application calls a system API.|
107| 401     | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.|
108
109**Example**
110
111```ts
112import { Callback } from '@kit.BasicServicesKit';
113
114let callback: Callback<boolean> = (data: boolean) => {
115  console.info('Listening enabled. Data: ' + JSON.stringify(data));
116};
117try {
118  display.on("privateModeChange", callback);
119} catch (exception) {
120  console.error('Failed to register callback. Code: ' + JSON.stringify(exception));
121}
122```
123
124## display.off('privateModeChange')<sup>10+</sup>
125
126off(type: 'privateModeChange', callback?: Callback&lt;boolean&gt;): void
127
128Unsubscribes from privacy mode changes of this display. When there is a privacy window in the foreground of the display, the display is in privacy mode, and the content in the privacy window cannot be captured or recorded.
129
130**System API**: This is a system API.
131
132**System capability**: SystemCapability.WindowManager.WindowManager.Core
133
134**Parameters**
135
136| Name  | Type                                      | Mandatory| Description                                                   |
137| -------- |------------------------------------------| ---- | ------------------------------------------------------- |
138| type     | string                                   | Yes  | Event type. The value is fixed at **'privateModeChange'**, indicating that the privacy mode of the display is changed.|
139| callback | Callback&lt;boolean&gt; | No  | Callback used to return whether the privacy mode of the display is changed. **true** if changed, **false** otherwise. If this parameter is not specified, all subscriptions to the specified event are canceled.|
140
141**Error codes**
142
143For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
144
145| ID| Error Message|
146| ------- | ----------------------- |
147| 202     | Permission verification failed. A non-system application calls a system API.|
148| 401     | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.|
149
150**Example**
151
152```ts
153try {
154  display.off("privateModeChange");
155} catch (exception) {
156  console.error('Failed to unregister callback. Code: ' + JSON.stringify(exception));
157}
158```
159
160## display.setFoldDisplayMode<sup>10+</sup>
161setFoldDisplayMode(mode: FoldDisplayMode): void
162
163Sets the display mode of the foldable device. This API is unavailable for 2-in-1 devices.
164
165**System API**: This is a system API.
166
167**System capability**: SystemCapability.Window.SessionManager
168
169**Parameters**
170
171| Name  | Type                                      | Mandatory| Description                                                   |
172| -------- |------------------------------------------| ---- | ------------------------------------------------------- |
173| mode     | [FoldDisplayMode](js-apis-display.md#folddisplaymode10)    | Yes  | Display mode.|
174
175**Error codes**
176
177For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md).
178
179| ID| Error Message|
180| ------- | ----------------------- |
181| 202     | Permission verification failed. A non-system application calls a system API.|
182| 401     | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.|
183| 1400003 | This display manager service works abnormally. |
184
185**Example**
186
187```ts
188import { display } from '@kit.ArkUI';
189
190try {
191  let mode: display.FoldDisplayMode = display.FoldDisplayMode.FOLD_DISPLAY_MODE_FULL;
192  display.setFoldDisplayMode(mode);
193} catch (exception) {
194  console.error('Failed to change the fold display mode. Code: ' + JSON.stringify(exception));
195}
196```
197
198## display.setFoldDisplayMode<sup>19+</sup>
199setFoldDisplayMode(mode: FoldDisplayMode, reason: string): void
200
201Sets the display mode of the foldable device, with the reason for the change specified. This API is unavailable for 2-in-1 devices.
202
203**System API**: This is a system API.
204
205**System capability**: SystemCapability.Window.SessionManager
206
207**Parameters**
208
209| Name  | Type                                      | Mandatory| Description                                                   |
210| -------- |------------------------------------------| ---- | ------------------------------------------------------- |
211| mode     | [FoldDisplayMode](js-apis-display.md#folddisplaymode10)    | Yes  | Display mode.|
212| reason     | string    | Yes  | Reason for changing the display mode. If this parameter is not set, an empty string is used by default.|
213
214**Error codes**
215
216For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md).
217
218| ID| Error Message|
219| ------- | ----------------------- |
220| 202     | Permission verification failed. A non-system application calls a system API.|
221| 1400003 | This display manager service works abnormally. |
222
223**Example**
224
225```ts
226import { display } from '@kit.ArkUI';
227
228try {
229  let mode: display.FoldDisplayMode = display.FoldDisplayMode.FOLD_DISPLAY_MODE_MAIN;
230  display.setFoldDisplayMode(mode, 'backSelfie');
231} catch (exception) {
232  console.error(`Failed to change the fold display mode. Code: ${exception}`);
233}
234```
235
236## display.setFoldStatusLocked<sup>11+</sup>
237setFoldStatusLocked(locked: boolean): void
238
239Sets whether to lock the current fold status of the foldable device.
240
241**System API**: This is a system API.
242
243**System capability**: SystemCapability.Window.SessionManager
244
245**Parameters**
246
247| Name  | Type                                      | Mandatory| Description                                                   |
248| -------- |------------------------------------------| ---- | ------------------------------------------------------- |
249| locked     | boolean    | Yes  | Whether to lock the current fold status of the foldable device. **true** to lock, **false** otherwise.|
250
251**Error codes**
252
253For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md).
254
255| ID| Error Message|
256| ------- | ----------------------- |
257| 202     | Permission verification failed. A non-system application calls a system API.|
258| 401     | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.|
259| 1400003 | This display manager service works abnormally. |
260
261**Example**
262
263```ts
264import { display } from '@kit.ArkUI';
265
266try {
267  let locked: boolean = false;
268  display.setFoldStatusLocked(locked);
269} catch (exception) {
270  console.error('Failed to change the fold status locked mode. Code: ' + JSON.stringify(exception));
271}
272```
273
274## display.addVirtualScreenBlocklist<sup>18+</sup>
275addVirtualScreenBlocklist(windowIds: Array\<number>): Promise\<void>
276
277Adds windows to the list of windows that are not allowed to be displayed during casting. This API takes effect only for the main window of an application or system windows. This API uses a promise to return the result.
278
279**System API**: This is a system API.
280
281**System capability**: SystemCapability.Window.SessionManager
282
283**Parameters**
284
285| Name  | Type                                      | Mandatory| Description                                                   |
286| -------- |------------------------------------------| ---- | ------------------------------------------------------- |
287| windowIds     | Array\<number>    | Yes  | List of window IDs. If a child window ID is passed in, it will not take effect. The window ID is an integer greater than 0. You are advised to call [getWindowProperties()](arkts-apis-window-Window.md#getwindowproperties9) to obtain the window ID.|
288
289**Return value**
290
291| Type| Description|
292| ------------------- | ------------------------ |
293| Promise&lt;void&gt; | Promise that returns no value.|
294
295**Error codes**
296
297For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md).
298
299| ID| Error Message|
300| ------- | ----------------------- |
301| 202     | Permission verification failed. A non-system application calls a system API.|
302| 401     | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.|
303| 801     | Capability not supported.Function addVirtualScreenBlocklist can not work correctly due to limited device capabilities. |
304| 1400003 | This display manager service works abnormally. |
305
306**Example**
307
308```ts
309import { BusinessError } from '@kit.BasicServicesKit';
310import { display, window } from '@kit.ArkUI';
311
312export default class EntryAbility extends UIAbility {
313  // ...
314  onWindowStageCreate(windowStage: window.WindowStage) {
315    // ...
316    let windowId = windowStage.getMainWindowSync().getWindowProperties().id;
317    let windowIds = [windowId];
318
319    let promise = display.addVirtualScreenBlocklist(windowIds);
320    promise.then(() => {
321      console.info('Succeeded in adding virtual screen blocklist.');
322    }).catch((err: BusinessError) => {
323      console.error('Failed to add virtual screen blocklist. Code: ' + JSON.stringify(err));
324    })
325  }
326}
327```
328
329## display.removeVirtualScreenBlocklist<sup>18+</sup>
330removeVirtualScreenBlocklist(windowIds: Array\<number>): Promise\<void>
331
332Removes windows from the list of windows that are not allowed to be displayed during casting. This API takes effect only for the main window of an application or system windows. This API uses a promise to return the result.
333
334**System API**: This is a system API.
335
336**System capability**: SystemCapability.Window.SessionManager
337
338**Parameters**
339
340| Name  | Type                                      | Mandatory| Description                                                   |
341| -------- |------------------------------------------| ---- | ------------------------------------------------------- |
342| windowIds     | Array\<number>    | Yes  | List of window IDs. If a child window ID is passed in, it will not take effect. The window ID is an integer greater than 0. You are advised to call [getWindowProperties()](arkts-apis-window-Window.md#getwindowproperties9) to obtain the window ID.|
343
344**Return value**
345
346| Type| Description|
347| ------------------- | ------------------------ |
348| Promise&lt;void&gt; | Promise that returns no value.|
349
350**Error codes**
351
352For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md).
353
354| ID| Error Message|
355| ------- | ----------------------- |
356| 202     | Permission verification failed. A non-system application calls a system API.|
357| 401     | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.|
358| 801     | Capability not supported.Function removeVirtualScreenBlocklist can not work correctly due to limited device capabilities. |
359| 1400003 | This display manager service works abnormally. |
360
361**Example**
362
363```ts
364import { BusinessError } from '@kit.BasicServicesKit';
365import { display, window } from '@kit.ArkUI';
366
367export default class EntryAbility extends UIAbility {
368  // ...
369  onWindowStageCreate(windowStage: window.WindowStage) {
370    // ...
371    let windowId = windowStage.getMainWindowSync().getWindowProperties().id;
372    let windowIds = [windowId];
373
374    let promise = display.addVirtualScreenBlocklist(windowIds);
375    promise.then(() => {
376      console.info('Succeeded in adding virtual screen blocklist.');
377    }).catch((err: BusinessError) => {
378      console.error('Failed to add virtual screen blocklist. Code: ' + JSON.stringify(err));
379    })
380
381    promise = display.removeVirtualScreenBlocklist(windowIds);
382    promise.then(() => {
383      console.info('Succeeded in removing virtual screen blocklist.');
384    }).catch((err: BusinessError) => {
385      console.error('Failed to remove virtual screen blocklist. Code: ' + JSON.stringify(err));
386    })
387  }
388}
389```
390
391## Display
392Implements a Display instance, with properties and APIs defined.
393
394Before calling any API in Display, you must use [getAllDisplays()](js-apis-display.md#displaygetalldisplays9) or [getDefaultDisplaySync()](js-apis-display.md#displaygetdefaultdisplaysync9) to obtain a Display instance.
395
396### hasImmersiveWindow<sup>11+</sup>
397hasImmersiveWindow(callback: AsyncCallback&lt;boolean&gt;): void
398
399Checks whether this display contains an immersive window. This API uses an asynchronous callback to return the result.
400
401**System API**: This is a system API.
402
403**System capability**: SystemCapability.Window.SessionManager
404
405**Parameters**
406
407| Name     | Type                       | Mandatory| Description                                                        |
408| ----------- | --------------------------- | ---- | ------------------------------------------------------------ |
409| callback    | AsyncCallback&lt;boolean&gt;   | Yes  | Callback used to return the result. **true** if the display contains an immersive window, **false** otherwise.|
410
411**Error codes**
412
413For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md).
414
415| ID| Error Message|
416| ------- | ----------------------- |
417| 202     | Permission verification failed. A non-system application calls a system API.|
418| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
419| 1400001 | Invalid display or screen. |
420| 1400003 | This display manager service works abnormally. |
421
422**Example**
423
424```ts
425import { BusinessError } from '@kit.BasicServicesKit';
426import { display } from '@kit.ArkUI';
427
428let displayClass: display.Display | null = null;
429displayClass = display.getDefaultDisplaySync();
430displayClass.hasImmersiveWindow((err: BusinessError, data) => {
431    const errCode: number = err.code;
432    if (errCode) {
433      console.error('Failed to check whether there is immersive window. Code: ' + JSON.stringify(err));
434      return;
435    }
436    console.info('Succeeded in checking whether there is immersive window. data: ' + JSON.stringify(data));
437});
438```
439### hasImmersiveWindow<sup>11+</sup>
440hasImmersiveWindow(): Promise&lt;boolean&gt;
441
442Checks whether this display contains an immersive window. This API uses a promise to return the result.
443
444**System API**: This is a system API.
445
446**System capability**: SystemCapability.Window.SessionManager
447
448**Return value**
449
450| Type               | Description                     |
451| ------------------- | ------------------------- |
452| Promise&lt;boolean&gt; | Promise used to return the result. **true** if the display contains an immersive window, **false** otherwise.|
453
454**Error codes**
455
456For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Display Error Codes](errorcode-display.md).
457
458| ID| Error Message|
459| ------- | ----------------------- |
460| 202     | Permission verification failed. A non-system application calls a system API.|
461| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
462| 1400001 | Invalid display or screen. |
463| 1400003 | This display manager service works abnormally. |
464
465**Example**
466
467```ts
468import { BusinessError } from '@kit.BasicServicesKit';
469import { display } from '@kit.ArkUI';
470
471let displayClass: display.Display | null = null;
472displayClass = display.getDefaultDisplaySync();
473let promise = displayClass.hasImmersiveWindow();
474promise.then((data) => {
475  console.info('Succeeded in checking whether there is immersive window. data: ' + JSON.stringify(data));
476}).catch((err: BusinessError) => {
477  console.error('Failed to check whether there is immersive window. Code: ' + JSON.stringify(err));
478})
479```
480