commonroutesServer/www/plugins/cordova-plugin-statusbar/README.md
www/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
116Permissions
117-----------
118
119#### config.xml
120
121 <feature name="StatusBar">
122 <param name="ios-package" value="CDVStatusBar" onload="true" />
123 </feature>
124
125StatusBar.overlaysWebView
126=================
127
128On iOS 7, make the statusbar overlay or not overlay the WebView.
129
130 StatusBar.overlaysWebView(true);
131
132Description
133-----------
134
135On 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.
136
137
138Supported Platforms
139-------------------
140
141- iOS
142
143Quick Example
144-------------
145
146 StatusBar.overlaysWebView(true);
147 StatusBar.overlaysWebView(false);
148
149StatusBar.styleDefault
150=================
151
152Use the default statusbar (dark text, for light backgrounds).
153
154 StatusBar.styleDefault();
155
156
157Supported Platforms
158-------------------
159
160- iOS
161- Windows Phone 7
162- Windows Phone 8
163- Windows Phone 8.1
164
165StatusBar.styleLightContent
166=================
167
168Use the lightContent statusbar (light text, for dark backgrounds).
169
170 StatusBar.styleLightContent();
171
172
173Supported Platforms
174-------------------
175
176- iOS
177- Windows Phone 7
178- Windows Phone 8
179- Windows Phone 8.1
180
181StatusBar.styleBlackTranslucent
182=================
183
184Use the blackTranslucent statusbar (light text, for dark backgrounds).
185
186 StatusBar.styleBlackTranslucent();
187
188
189Supported Platforms
190-------------------
191
192- iOS
193- Windows Phone 7
194- Windows Phone 8
195- Windows Phone 8.1
196
197StatusBar.styleBlackOpaque
198=================
199
200Use the blackOpaque statusbar (light text, for dark backgrounds).
201
202 StatusBar.styleBlackOpaque();
203
204
205Supported Platforms
206-------------------
207
208- iOS
209- Windows Phone 7
210- Windows Phone 8
211- Windows Phone 8.1
212
213
214StatusBar.backgroundColorByName
215=================
216
217On iOS 7, when you set StatusBar.statusBarOverlaysWebView to false, you can set the background color of the statusbar by color name.
218
219 StatusBar.backgroundColorByName("red");
220
221Supported color names are:
222
223 black, darkGray, lightGray, white, gray, red, green, blue, cyan, yellow, magenta, orange, purple, brown
224
225
226Supported Platforms
227-------------------
228
229- iOS
230- Android 5+
231- Windows Phone 7
232- Windows Phone 8
233- Windows Phone 8.1
234
235StatusBar.backgroundColorByHexString
236=================
237
238Sets the background color of the statusbar by a hex string.
239
240 StatusBar.backgroundColorByHexString("#C0C0C0");
241
242CSS shorthand properties are also supported.
243
244 StatusBar.backgroundColorByHexString("#333"); // => #333333
245 StatusBar.backgroundColorByHexString("#FAB"); // => #FFAABB
246
247On iOS 7, when you set StatusBar.statusBarOverlaysWebView to false, you can set the background color of the statusbar by a hex string (#RRGGBB).
248
249On WP7 and WP8 you can also specify values as #AARRGGBB, where AA is an alpha value
250
251Supported Platforms
252-------------------
253
254- iOS
255- Android 5+
256- Windows Phone 7
257- Windows Phone 8
258- Windows Phone 8.1
259
260StatusBar.hide
261=================
262
263Hide the statusbar.
264
265 StatusBar.hide();
266
267
268Supported Platforms
269-------------------
270
271- iOS
272- Android
273- Windows Phone 7
274- Windows Phone 8
275- Windows Phone 8.1
276
277StatusBar.show
278=================
279
280Shows the statusbar.
281
282 StatusBar.show();
283
284
285Supported Platforms
286-------------------
287
288- iOS
289- Android
290- Windows Phone 7
291- Windows Phone 8
292- Windows Phone 8.1
293
294
295StatusBar.isVisible
296=================
297
298Read this property to see if the statusbar is visible or not.
299
300 if (StatusBar.isVisible) {
301 // do something
302 }
303
304
305Supported Platforms
306-------------------
307
308- iOS
309- Android
310- Windows Phone 7
311- Windows Phone 8
312- Windows Phone 8.1