• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Window Subsystem Changelog
2
3## cl.window.1 setWindowLayoutFullScreen and setImmersiveModeEnabledState Are Not Valid for 2-in-1 Devices
4
5**Access Level**
6
7Public API
8
9**Reason for Change**
10
11For mobile phones, immersive mode is characterized by full-screen application layouts that overlap with the system status bar and navigation bar. However, on 2-in-1 devices, full-screen windows tend to hide the system status bar and dock bar, which is different from the behavior on mobile phones. Therefore, the **setWindowLayoutFullScreen** and **setImmersiveModeEnabledState** APIs are disabled on 2-in-1 devices. Instead, the **maximize** API is used to enter or exit immersive mode, and the visibility of the status bar and dock bar is managed by the parameters passed to the **maximize** API.
12
13**Change Impact**
14
15This change is a non-compatible change.
16
17Before change: When the **setWindowLayoutFullScreen** and **setImmersiveModeEnabledState** APIs are called on 2-in-1 devices, the window enters or exits immersive mode.
18
19After change: The **setWindowLayoutFullScreen** and **setImmersiveModeEnabledState** APIs do not take effect on 2-in-1 devices.
20
21**Start API Level**
22
23API version 9 for **setWindowLayoutFullScreen**
24
25API version 12 for **setImmersiveModeEnabledState**
26
27**Change Since**
28
29OpenHarmony SDK 5.0.0.56
30
31**Key API/Component Changes**
32
33@ohos.window.d.ts
34
35System capability: SystemCapability.Window.SessionManager
36
37APIs: **setWindowLayoutFullScreen** and **setImmersiveModeEnabledState**
38
39**Adaptation Guide**
40
41To set the immersive state for a window on 2-in-1 devices, call [maximize](../../../application-dev/reference/apis-arkui/js-apis-window.md#maximize12).
42
43When calling [setWindowLayoutFullScreen](../../../application-dev/reference/apis-arkui/js-apis-window.md#setwindowlayoutfullscreen9), you are advised to call **maximize** at the same time.
44
45When calling [setImmersiveModeEnabledState](../../../application-dev/reference/apis-arkui/js-apis-window.md#setimmersivemodeenabledstate12), you are advised to call **maximize** at the same time.
46
47Example:
48
49```ts
50// EntryAbility.ets
51import { BusinessError } from '@kit.BasicServicesKit';
52
53export default class EntryAbility extends UIAbility {
54  // ...
55  onWindowStageCreate(windowStage: window.WindowStage): void {
56    console.info('onWindowStageCreate');
57    let windowClass: window.Window | undefined = undefined;
58    windowStage.getMainWindow((err: BusinessError, data) => {
59      const errCode: number = err.code;
60      if (errCode) {
61        console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
62        return;
63      }
64      windowClass = data;
65      let isLayoutFullScreen = true;
66      try {
67        let promise = windowClass.setWindowLayoutFullScreen(isLayoutFullScreen);
68        promise.then(() => {
69          console.info('Succeeded in setting the window layout to full-screen mode.');
70        }).catch((err: BusinessError) => {
71          console.error(`Failed to set the window layout to full-screen mode. Cause code: ${err.code}, message: ${err.message}`);
72        });
73      } catch (exception) {
74        console.error(`Failed to set the window layout to full-screen mode. Cause code: ${exception.code}, message: ${exception.message}`);
75      }
76
77      try {
78        let promise = windowClass.maximize(window.MaximizePresentation.ENTER_IMMERSIVE);
79        promise.then(() => {
80          console.info('Succeeded in maximizing the window.');
81        }).catch((err: BusinessError) => {
82          console.error(`Failed to maximize the window. Cause code: ${err.code}, message: ${err.message}`);
83        });
84      } catch (exception) {
85        console.error(`Failed to maximize the window. Cause code: ${exception.code}, message: ${exception.message}`);
86      }
87    });
88  }
89}
90```
91
92```ts
93// EntryAbility.ets
94import { BusinessError } from '@kit.BasicServicesKit';
95
96export default class EntryAbility extends UIAbility {
97  // ...
98  onWindowStageCreate(windowStage: window.WindowStage): void {
99    console.info('onWindowStageCreate');
100    let windowClass: window.Window | undefined = undefined;
101    windowStage.getMainWindow((err: BusinessError, data) => {
102      const errCode: number = err.code;
103      if (errCode) {
104        console.error(`Failed to obtain the main window. Cause code: ${err.code}, message: ${err.message}`);
105        return;
106      }
107      windowClass = data;
108      try {
109        let enabled = true;
110        windowClass.setImmersiveModeEnabledState(enabled);
111      } catch (exception) {
112        console.error(`Failed to set the window immersive mode enabled status. Cause code: ${exception.code}, message: ${exception.message}`);
113      }
114
115      try {
116        let promise = windowClass.maximize(window.MaximizePresentation.ENTER_IMMERSIVE);
117        promise.then(() => {
118          console.info('Succeeded in maximizing the window.');
119        }).catch((err: BusinessError) => {
120          console.error(`Failed to maximize the window. Cause code: ${err.code}, message: ${err.message}`);
121        });
122      } catch (exception) {
123        console.error(`Failed to maximize the window. Cause code: ${exception.code}, message: ${exception.message}`);
124      }
125    });
126  }
127}
128```
129