1# Using Display to Obtain Display Properties and Listen for Status Changes (ArkTS)
2
3## When to Use
4
5[Display](../reference/apis-arkui/js-apis-display.md) 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. Applications may adjust their UI in response to changes in the display information, display status, and folding states.
6
7Typical scenarios for utilizing display properties are as follows:
8
9- Display information query: You can query the display resolution, physical pixel density, logical pixel density, refresh rate, dimensions, rotation direction, and rotation angle. For details, see [Display Properties](../reference/apis-arkui/js-apis-display.md#properties).
10- Display status monitoring: You can listen for changes in the rotation, resolution, and refresh rate of the display.
11- Folding state monitoring: You can check whether the device is foldable and listen for changes in its folding state (whether it is unfolded or folded).
12
13## Available APIs
14
15The following table lists the common APIs related to display properties. For details, see [@ohos.display (Display)](../reference/apis-arkui/js-apis-display.md).
16
17| API                                                        | Description                                                        |
18| ------------------------------------------------------------ | ------------------------------------------------------------ |
19| getAllDisplays(): Promise<Array\<Display>>                   | Obtains all display objects. This API uses a promise to return the result.            |
20| getDefaultDisplaySync(): Display                             | Obtains the default display object. This API uses an asynchronous callback to return the result.                                 |
21| getDisplayByIdSync(displayId: number): Display               | Obtains a display object based on the display ID.                        |
22| on(type: 'add'\|'remove'\|'change', callback: Callback\<number>): void | Subscribes to display change events.                                    |
23| off(type: 'add'\|'remove'\|'change', callback?: Callback\<number>): void | Unsubscribes from display change events.                                    |
24| on(type: 'captureStatusChange', callback: Callback\<boolean>): void | Subscribes to screen capture, casting, or recording status change events.                    |
25| off(type: 'captureStatusChange', callback?: Callback\<boolean>): void | Unsubscribes from screen capture, casting, or recording status change events.                    |
26| on(type: 'availableAreaChange', callback: Callback\<Rect>): void | Subscribes to change events of the available area on the display of the current device. This API uses an asynchronous callback to return the result.|
27| off(type: 'availableAreaChange', callback?: Callback\<Rect>): void | Unsubscribes from change events of the available area on the display of the current device.                        |
28| isFoldable(): boolean                                        | Checks whether the current device is foldable.                                        |
29| on(type: 'foldStatusChange', callback: Callback\<FoldStatus>): void | Subscribes to fold status change events of the foldable device.                            |
30| off(type: 'foldStatusChange', callback?: Callback\<FoldStatus>): void | Unsubscribes from fold status change events of the foldable device.                            |
31
32## Obtaining a Display Object
33
34The display object provides APIs to obtain display properties and listen for changes. You can use any of the following methods to obtain a display object, depending on your service requirements:
35
36- Use **getDefaultDisplaySync()** to obtain the default display object.
37- Use **getAllDisplays()** to obtain all display objects.
38- Use **getDisplayByIdSync()** to obtain a display object with a specific display ID.
39
40The following example demonstrates how to use **getDefaultDisplaySync()** to obtain the default display object:
41
42```ts
43import { display } from '@kit.ArkUI';
44
45let displayClass: display.Display | null = null;
46displayClass = display.getDefaultDisplaySync();
47// Ensure that the display object, displayClass in this example, is obtained before the operations of querying the display properties and listening for events and status changes.
48```
49
50## Obtaining Display Properties
51
521. After the display object is acquired, you can query the basic information about the display through its properties.
53
54   ```ts
55   import { display } from '@kit.ArkUI';
56
57   let displayClass: display.Display | null = null;
58   displayClass = display.getDefaultDisplaySync();
59
60   // Obtain the display ID.
61   console.info(`The scree Id is ${displayClass.id}.`);
62   // Obtain the refresh rate.
63   console.info(`The screen is ${displayClass.refreshRate}.`);
64   // Obtain the display width.
65   console.info(`The screen width is ${displayClass.width}.`);
66   // Obtain the display height.
67   console.info(`The screen height is ${displayClass.height}.`);
68   // ...
69   ```
70
712. To enhance UI layout design, you can use **getCutoutInfo()** to obtain information about unusable areas of the display, including punch hole, notch, and curved area of a waterfall display. You can also use **getAvailableArea()** to obtain the available area of the display.
72
73   ```ts
74   import { BusinessError } from '@kit.BasicServicesKit';
75
76   displayClass.getCutoutInfo().then((cutoutInfo: display.CutoutInfo) => {
77     console.info('Succeeded in getting cutoutInfo. Data: ' + JSON.stringify(cutoutInfo));
78   }).catch((err: BusinessError) => {
79     console.error(`Failed to obtain all the display objects. Code: ${err.code}, message: ${err.message}`);
80   });
81
82   displayClass.getAvailableArea().then((availableArea) => {
83     console.info('Succeeded get the available area in this display. data: ' + JSON.stringify(availableArea));
84   }).catch((err: BusinessError) => {
85     console.error(`Failed to get the available area in this display. Code: ${err.code}, message: ${err.message}`);
86   });
87   ```
88
893. Call **display.isCaptured()** to determine whether the device is engaged in activities such as screen capture, casting, or recording.
90
91   ```ts
92   console.info(`The sceeen is captured or not : ${display.isCaptured()}`);
93   ```
94
95## Listening for Display Status Changes
96
971. To listen for display changes, use **display.on('add'|'remove'|'change')** to subscribe to events such as the addition, removal, or alteration of displays. To unsubscribe from these events, call **display.off('add'|'remove'|'change')**.
98
99   ```ts
100   import { display } from '@kit.ArkUI';
101   import { Callback } from '@kit.BasicServicesKit';
102
103   let callback1: Callback<number> = (data: number) => {
104     console.info('Listening enabled. Data: ' + JSON.stringify(data));
105   };
106   // The following uses the addition event as an example.
107   display.on("add", callback1);
108
109   // Unregister all the callbacks that have been registered through on().
110   display.off("add");
111   // Unregister a single callback.
112   display.off('add', callback1);
113   ```
114
1152. To listen for screen capture, casting, or recording status changes, call **display.on('captureStatusChange')**. To end the listening, call **display.off('captureStatusChange')**.
116
117   ```ts
118   let callback2: Callback<boolean> = (captureStatus: boolean) => {
119       // For captureStatus, the value true means that the device starts screen capture, casting, or recording, and false means that the device stops screen capture, casting, or recording.
120     console.info('Listening capture status: ' + captureStatus);
121   };
122   // Listen for screen capture, casting, or recording status changes.
123   display.on('captureStatusChange', callback2);
124
125   display.off('captureStatusChange', callback2);
126   ```
127
1283. To listen for available area changes of the display, call **on('availableAreaChange')**. To end the listening, call **off('availableAreaChange')**.
129
130   ```ts
131   import { Callback } from '@kit.BasicServicesKit';
132   import { display } from '@kit.ArkUI';
133
134   let callback3: Callback<display.Rect> = (data: display.Rect) => {
135     console.info('Listening enabled. Data: ' + JSON.stringify(data));
136   };
137   let displayClass: display.Display | null = null;
138   try {
139     displayClass = display.getDefaultDisplaySync();
140     // Listen for changes of the available area on the display.
141     displayClass.on("availableAreaChange", callback3);
142   } catch (exception) {
143     console.error(`Failed to register callback. Code: ${exception.code}, message: ${exception.message}`);
144   }
145   // End the listening.
146   displayClass.off("availableAreaChange", callback3);
147   ```
148
149## Listening for Folding State Changes
150
1511. Call **display.isFoldable()** to check whether the device is foldable.
152
153   ```
154   import { display } from '@kit.ArkUI';
155
156   let ret: boolean = false;
157   ret = display.isFoldable();
158   ```
159
1602. If the device is a foldable device, call **display.on('foldStatusChange')** to listen for folding state changes. To end the listening, call **display.on('foldStatusChange')**.
161
162   ```ts
163   import { Callback } from '@kit.BasicServicesKit';
164
165   /**
166    * The callback parameter used for subscription must be passed as an object.
167    * If an anonymous function is used for registration, a new underlying object is created each time the function is called, causing memory leakage.
168   */
169   let callback: Callback<display.FoldStatus> = (data: display.FoldStatus) => {
170     console.info('Listening enabled. Data: ' + JSON.stringify(data));
171   };
172   display.on('foldStatusChange', callback);
173
174   // Unregister all the callbacks that have been registered through on().
175   display.off('foldStatusChange');
176   // Unregister a single callback.
177   display.off('foldStatusChange', callback);
178   ```
179