• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Window Subsystem Changelog
2
3## cl.window.1 Changed the Return Values of getWindowStatus and on('windowStatusChange') on 2-in-1 Devices When the Window Is Maximized
4
5**Access Level**
6
7Public API
8
9**Reason for Change**
10
11When the window is maximized, the **getWindowStatus** and **on('windowStatusChange')** APIs return **WindowStatusType::FULL_SCREEN**.
12
13The application cannot tell whether the window is in the maximized state or full-screen mode on 2-in-1 devices from the return values.
14
15**Change Impact**
16
17This change is a non-compatible change.
18
19Before change: When **getWindowStatus** and **on('windowStatusChange')** are called on 2-in-1 devices, the return value is **WindowStatusType::FULL_SCREEN** when the window is maximized.
20
21After change: When **getWindowStatus** and **on('windowStatusChange')** are called on 2-in-1 devices, the return value is **WindowStatusType::MAXIMIZE** when the window is maximized.
22
23**Start API Level**
24
2511 for **on('windowStatusChange')**
26
2712 for **getWindowStatus interface** on 2-in-1 devices
28
29**Change Since**
30
31OpenHarmony SDK 5.0.1.45
32
33**Key API/Component Changes**
34
35@ohos.window.d.ts
36
37System capability: SystemCapability.Window.SessionManager
38
39APIs: getWindowStatus and on('windowStatusChange')
40
41**Adaptation Guide**
42
43To distinguish whether the window is maximized or in full-screen mode on 2-in-1 devices, implement as follows:
44
45- In API version 13 and earlier, in the case that **WindowStatusType::FULL_SCREEN** is returned, call [getImmersiveModeEnabledState()](../../../application-dev/reference/apis-arkui/js-apis-window.md#getimmersivemodeenabledstate12). If **true** is returned, the window is in full-screen mode. If **false** is returned, the window is maximized.
46
47- In API version 14 and later, you can directly call **getWindowStatus** and **on('windowStatusChange')** to distinguish the maximized state from full-screen mode.
48
49  However, you must adjust the code to match the return value. If the same code logic is used for **WindowStatusType::FULL_SCREEN** and **WindowStatusType::MAXIMIZE**, just append a check for **WindowStatusType::MAXIMIZE** (using a logical OR) within the existing logic. If different logic is used for **WindowStatusType::FULL_SCREEN** and **WindowStatusType::MAXIMIZE**, you must introduce a separate condition for **WindowStatusType::MAXIMIZE** to manage the window maximization logic.
50
51The following example uses the **on('windowStatusChange')** API as an example to describe how to distinguish the maximized state and full-screen mode on 2-in-1 devices.
52
53Example for API version 13 and earlier versions:
54```ts
55// EntryAbility.ets
56import { BusinessError } from '@kit.BasicServicesKit';
57
58export default class EntryAbility extends UIAbility {
59  // ...
60  onWindowStageCreate(windowStage: window.WindowStage) {
61    console.info('onWindowStageCreate');
62    try {
63      let windowClass = windowStage.getMainWindowSync();
64      windowClass?.on("windowStatusChange", (windowStatusType: window.WindowStatusType) => {
65        if (windowStatusType == window.WindowStatusType.FULL_SCREEN) {
66          // If isFullScreen is true, the window is in full-screen mode; if it is false, the window is maximized.
67          let isFullScreen: boolean = windowClass.getImmersiveModeEnabledState();
68        } else {
69          // ...
70        }
71      })
72    } catch (exception) {
73      console.error(`Failed to obtain the main window. Cause code: ${exception.code}, message: ${exception.message}`);
74    }
75  }
76}
77```
78
79Example for API version 14:
80```ts
81// EntryAbility.ets
82import { BusinessError } from '@kit.BasicServicesKit';
83
84export default class EntryAbility extends UIAbility {
85  // ...
86  onWindowStageCreate(windowStage: window.WindowStage) {
87    console.info('onWindowStageCreate');
88    try {
89      let windowClass = windowStage.getMainWindowSync();
90      windowClass?.on("windowStatusChange", (windowStatusType: window.WindowStatusType) => {
91        // Different logic is used for the full-screen mode and maximized state. Add a separate condition for window.WindowStatusType.MAXIMIZE.
92        if (windowStatusType == window.WindowStatusType.FULL_SCREEN) {
93          // ....
94        } else if (windowStatusType == window.WindowStatusType.MAXIMIZE) {
95          // ...
96        } else {
97          // ...
98        }
99      })
100    } catch (exception) {
101      console.error(`Failed to obtain the main window. Cause code: ${exception.code}, message: ${exception.message}`);
102    }
103  }
104}
105```
106
107Example for API version 14 without distinguishing maximized state:
108```ts
109// EntryAbility.ets
110import { BusinessError } from '@kit.BasicServicesKit';
111
112export default class EntryAbility extends UIAbility {
113  // ...
114  onWindowStageCreate(windowStage: window.WindowStage) {
115    console.info('onWindowStageCreate');
116    try {
117      let windowClass = windowStage.getMainWindowSync();
118      windowClass?.on("windowStatusChange", (windowStatusType: window.WindowStatusType) => {
119        // The same logic is used for the full-screen mode and maximized state. Add a check using OR for window.WindowStatusType.MAXIMIZE.
120        if (windowStatusType == window.WindowStatusType.FULL_SCREEN ||
121            windowStatusType == window.WindowStatusType.MAXIMIZE) {
122          // ....
123        } else {
124          // ...
125        }
126      })
127    } catch (exception) {
128      console.error(`Failed to obtain the main window. Cause code: ${exception.code}, message: ${exception.message}`);
129    }
130  }
131}
132```
133
134## cl.window.2 Changed the Return Values of hasImmersiveWindow on 2-in-1 Devices When the Window Is Maximized
135
136**Access Level**
137
138System API
139
140**Reason for Change**
141
142When the **hasImmersiveWindow** API is called on a 2-in-1 device, the return value is **true** if the window is maximized, which is inconsistent with the actual situation.
143
144This API cannot be used to determine whether any window is maximized or in full screen mode on 2-in-1 devices, which does not comply with the API functionality design.
145
146**Change Impact**
147
148This change is a non-compatible change.
149
150Before change: On 2-in-1 devices, calling **hasImmersiveWindow** when the window is in a maximized state returns true.
151
152After change: On 2-in-1 devices, calling **hasImmersiveWindow** when the window is in a maximized state returns false.
153
154**Start API Level**
155
156API version 11 for **hasImmersiveWindow**
157
158**Change Since**
159
160OpenHarmony SDK 5.0.1.45
161
162**Key API/Component Changes**
163
164@ohos.display.d.ts
165
166System capability: SystemCapability.Window.SessionManager
167
168API: **hasImmersiveWindow**
169
170**Adaptation Guide**
171
172Review your application implementation to see if there are any calls to **hasImmersiveWindow** to determine whether the current screen contains a full-screen window. If so, you need to adjust the code based on the change in return value.
173