openEventsPlatformApp/plugins/cordova-plugin-statusbar/README.md
plugins/cordova-plugin-statusbar/README.mdRaw
1---
2title: Statusbar
3description: Control the device status bar.
4---
5<!---
6# license: Licensed to the Apache Software Foundation (ASF) under one
7# or more contributor license agreements. See the NOTICE file
8# distributed with this work for additional information
9# regarding copyright ownership. The ASF licenses this file
10# to you under the Apache License, Version 2.0 (the
11# "License"); you may not use this file except in compliance
12# with the License. You may obtain a copy of the License at
13#
14# http://www.apache.org/licenses/LICENSE-2.0
15#
16# Unless required by applicable law or agreed to in writing,
17# software distributed under the License is distributed on an
18# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
19# KIND, either express or implied. See the License for the
20# specific language governing permissions and limitations
21# under the License.
22-->
23
24|Android|iOS| Windows 8.1 Store | Windows 8.1 Phone | Windows 10 Store | Travis CI |
25|:-:|:-:|:-:|:-:|:-:|:-:|
26|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=android,PLUGIN=cordova-plugin-statusbar/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=ios,PLUGIN=cordova-plugin-statusbar/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-8.1-store,PLUGIN=cordova-plugin-statusbar/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-8.1-phone,PLUGIN=cordova-plugin-statusbar/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-10-store,PLUGIN=cordova-plugin-statusbar/)|[](https://travis-ci.org/apache/cordova-plugin-statusbar)|
27
28# cordova-plugin-statusbar
29
30StatusBar
31======
32
33> The `StatusBar` object provides some functions to customize the iOS and Android StatusBar.
34
35:warning: Report issues on the [Apache Cordova issue tracker](https://issues.apache.org/jira/issues/?jql=project%20%3D%20CB%20AND%20status%20in%20%28Open%2C%20%22In%20Progress%22%2C%20Reopened%29%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20%22Plugin%20Statusbar%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC)
36
37
38## Installation
39
40This installation method requires cordova 5.0+
41
42 cordova plugin add cordova-plugin-statusbar
43Older versions of cordova can still install via the __deprecated__ id
44
45 cordova plugin add org.apache.cordova.statusbar
46It is also possible to install via repo url directly ( unstable )
47
48 cordova plugin add https://github.com/apache/cordova-plugin-statusbar.git
49
50
51Preferences
52-----------
53
54#### config.xml
55
56- __StatusBarOverlaysWebView__ (boolean, defaults to true). On iOS 7, make the statusbar overlay or not overlay the WebView at startup.
57
58 <preference name="StatusBarOverlaysWebView" value="true" />
59
60- __StatusBarBackgroundColor__ (color hex string, no default value). On iOS 7, set the background color of the statusbar by a hex string (#RRGGBB) at startup. If this value is not set, the background color will be transparent.
61
62 <preference name="StatusBarBackgroundColor" value="#000000" />
63
64- __StatusBarStyle__ (status bar style, defaults to lightcontent). On iOS 7, set the status bar style. Available options default, lightcontent, blacktranslucent, blackopaque.
65
66 <preference name="StatusBarStyle" value="lightcontent" />
67
68### Android Quirks
69The Android 5+ guidelines specify using a different color for the statusbar than your main app color (unlike the uniform statusbar color of many iOS 7+ apps), so you may want to set the statusbar color at runtime instead via `StatusBar.backgroundColorByHexString` or `StatusBar.backgroundColorByName`. One way to do that would be:
70```js
71if (cordova.platformId == 'android') {
72 StatusBar.backgroundColorByHexString("#333");
73}
74```
75
76Hiding at startup
77-----------
78
79During runtime you can use the StatusBar.hide function below, but if you want the StatusBar to be hidden at app startup, you must modify your app's Info.plist file.
80
81Add/edit these two attributes if not present. Set **"Status bar is initially hidden"** to **"YES"** and set **"View controller-based status bar appearance"** to **"NO"**. If you edit it manually without Xcode, the keys and values are:
82
83
84 <key>UIStatusBarHidden</key>
85 <true/>
86 <key>UIViewControllerBasedStatusBarAppearance</key>
87 <false/>
88
89
90Methods
91-------
92This plugin defines global `StatusBar` object.
93
94Although in the global scope, it is not available until after the `deviceready` event.
95
96 document.addEventListener("deviceready", onDeviceReady, false);
97 function onDeviceReady() {
98 console.log(StatusBar);
99 }
100
101- StatusBar.overlaysWebView
102- StatusBar.styleDefault
103- StatusBar.styleLightContent
104- StatusBar.styleBlackTranslucent
105- StatusBar.styleBlackOpaque
106- StatusBar.backgroundColorByName
107- StatusBar.backgroundColorByHexString
108- StatusBar.hide
109- StatusBar.show
110
111Properties
112--------
113
114- StatusBar.isVisible
115
116Events
117------
118
119- statusTap
120
121Permissions
122-----------
123
124#### config.xml
125
126 <feature name="StatusBar">
127 <param name="ios-package" value="CDVStatusBar" onload="true" />
128 </feature>
129
130StatusBar.overlaysWebView
131=================
132
133On iOS 7, make the statusbar overlay or not overlay the WebView.
134
135 StatusBar.overlaysWebView(true);
136
137Description
138-----------
139
140On iOS 7, set to false to make the statusbar appear like iOS 6. Set the style and background color to suit using the other functions.
141
142
143Supported Platforms
144-------------------
145
146- iOS
147
148Quick Example
149-------------
150
151 StatusBar.overlaysWebView(true);
152 StatusBar.overlaysWebView(false);
153
154StatusBar.styleDefault
155=================
156
157Use the default statusbar (dark text, for light backgrounds).
158
159 StatusBar.styleDefault();
160
161
162Supported Platforms
163-------------------
164
165- iOS
166- Windows Phone 7
167- Windows Phone 8
168- Windows Phone 8.1
169
170StatusBar.styleLightContent
171=================
172
173Use the lightContent statusbar (light text, for dark backgrounds).
174
175 StatusBar.styleLightContent();
176
177
178Supported Platforms
179-------------------
180
181- iOS
182- Windows Phone 7
183- Windows Phone 8
184- Windows Phone 8.1
185
186StatusBar.styleBlackTranslucent
187=================
188
189Use the blackTranslucent statusbar (light text, for dark backgrounds).
190
191 StatusBar.styleBlackTranslucent();
192
193
194Supported Platforms
195-------------------
196
197- iOS
198- Windows Phone 7
199- Windows Phone 8
200- Windows Phone 8.1
201
202StatusBar.styleBlackOpaque
203=================
204
205Use the blackOpaque statusbar (light text, for dark backgrounds).
206
207 StatusBar.styleBlackOpaque();
208
209
210Supported Platforms
211-------------------
212
213- iOS
214- Windows Phone 7
215- Windows Phone 8
216- Windows Phone 8.1
217
218
219StatusBar.backgroundColorByName
220=================
221
222On iOS 7, when you set StatusBar.statusBarOverlaysWebView to false, you can set the background color of the statusbar by color name.
223
224 StatusBar.backgroundColorByName("red");
225
226Supported color names are:
227
228 black, darkGray, lightGray, white, gray, red, green, blue, cyan, yellow, magenta, orange, purple, brown
229
230
231Supported Platforms
232-------------------
233
234- iOS
235- Android 5+
236- Windows Phone 7
237- Windows Phone 8
238- Windows Phone 8.1
239
240StatusBar.backgroundColorByHexString
241=================
242
243Sets the background color of the statusbar by a hex string.
244
245 StatusBar.backgroundColorByHexString("#C0C0C0");
246
247CSS shorthand properties are also supported.
248
249 StatusBar.backgroundColorByHexString("#333"); // => #333333
250 StatusBar.backgroundColorByHexString("#FAB"); // => #FFAABB
251
252On iOS 7, when you set StatusBar.statusBarOverlaysWebView to false, you can set the background color of the statusbar by a hex string (#RRGGBB).
253
254On WP7 and WP8 you can also specify values as #AARRGGBB, where AA is an alpha value
255
256Supported Platforms
257-------------------
258
259- iOS
260- Android 5+
261- Windows Phone 7
262- Windows Phone 8
263- Windows Phone 8.1
264
265StatusBar.hide
266=================
267
268Hide the statusbar.
269
270 StatusBar.hide();
271
272
273Supported Platforms
274-------------------
275
276- iOS
277- Android
278- Windows Phone 7
279- Windows Phone 8
280- Windows Phone 8.1
281
282StatusBar.show
283=================
284
285Shows the statusbar.
286
287 StatusBar.show();
288
289
290Supported Platforms
291-------------------
292
293- iOS
294- Android
295- Windows Phone 7
296- Windows Phone 8
297- Windows Phone 8.1
298
299
300StatusBar.isVisible
301=================
302
303Read this property to see if the statusbar is visible or not.
304
305 if (StatusBar.isVisible) {
306 // do something
307 }
308
309
310Supported Platforms
311-------------------
312
313- iOS
314- Android
315- Windows Phone 7
316- Windows Phone 8
317- Windows Phone 8.1
318
319
320statusTap
321=========
322
323Listen for this event to know if the statusbar was tapped.
324
325 window.addEventListener('statusTap', function() {
326 // scroll-up with document.body.scrollTop = 0; or do whatever you want
327 });
328
329
330Supported Platforms
331-------------------
332
333- iOS