diff --git a/README.md b/README.md index 1c58fe0..b901a31 100644 --- a/README.md +++ b/README.md @@ -17,8 +17,281 @@ under the License. --> -# org.apache.cordova.statusbar +# cordova-plugin-statusbar [![Build Status](https://travis-ci.org/apache/cordova-plugin-statusbar.svg)](https://travis-ci.org/apache/cordova-plugin-statusbar) -Plugin documentation: [doc/index.md](doc/index.md) \ No newline at end of file +StatusBar +====== + +> The `StatusBar` object provides some functions to customize the iOS and Android StatusBar. + + +## Installation + + cordova plugin add cordova-plugin-statusbar + +Preferences +----------- + +#### config.xml + +- __StatusBarOverlaysWebView__ (boolean, defaults to true). On iOS 7, make the statusbar overlay or not overlay the WebView at startup. + + + +- __StatusBarBackgroundColor__ (color hex string, defaults to #000000). On iOS 7 and Android 5, set the background color of the statusbar by a hex string (#RRGGBB) at startup. + + + +- __StatusBarStyle__ (status bar style, defaults to lightcontent). On iOS 7, set the status bar style. Available options default, lightcontent, blacktranslucent, blackopaque. + + + +### Android Quirks +The 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: +```js +if (cordova.platformId == 'android') { + StatusBar.backgroundColorByHexString("#333"); +} +``` + +Hiding at startup +----------- + +During 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. + +Add/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: + + + UIStatusBarHidden + + UIViewControllerBasedStatusBarAppearance + + + +Methods +------- +This plugin defines global `StatusBar` object. + +Although in the global scope, it is not available until after the `deviceready` event. + + document.addEventListener("deviceready", onDeviceReady, false); + function onDeviceReady() { + console.log(StatusBar); + } + +- StatusBar.overlaysWebView +- StatusBar.styleDefault +- StatusBar.styleLightContent +- StatusBar.styleBlackTranslucent +- StatusBar.styleBlackOpaque +- StatusBar.backgroundColorByName +- StatusBar.backgroundColorByHexString +- StatusBar.hide +- StatusBar.show + +Properties +-------- + +- StatusBar.isVisible + +Permissions +----------- + +#### config.xml + + + + + +StatusBar.overlaysWebView +================= + +On iOS 7, make the statusbar overlay or not overlay the WebView. + + StatusBar.overlaysWebView(true); + +Description +----------- + +On 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. + + +Supported Platforms +------------------- + +- iOS + +Quick Example +------------- + + StatusBar.overlaysWebView(true); + StatusBar.overlaysWebView(false); + +StatusBar.styleDefault +================= + +Use the default statusbar (dark text, for light backgrounds). + + StatusBar.styleDefault(); + + +Supported Platforms +------------------- + +- iOS +- Windows Phone 7 +- Windows Phone 8 +- Windows Phone 8.1 + +StatusBar.styleLightContent +================= + +Use the lightContent statusbar (light text, for dark backgrounds). + + StatusBar.styleLightContent(); + + +Supported Platforms +------------------- + +- iOS +- Windows Phone 7 +- Windows Phone 8 +- Windows Phone 8.1 + +StatusBar.styleBlackTranslucent +================= + +Use the blackTranslucent statusbar (light text, for dark backgrounds). + + StatusBar.styleBlackTranslucent(); + + +Supported Platforms +------------------- + +- iOS +- Windows Phone 7 +- Windows Phone 8 +- Windows Phone 8.1 + +StatusBar.styleBlackOpaque +================= + +Use the blackOpaque statusbar (light text, for dark backgrounds). + + StatusBar.styleBlackOpaque(); + + +Supported Platforms +------------------- + +- iOS +- Windows Phone 7 +- Windows Phone 8 +- Windows Phone 8.1 + + +StatusBar.backgroundColorByName +================= + +On iOS 7, when you set StatusBar.statusBarOverlaysWebView to false, you can set the background color of the statusbar by color name. + + StatusBar.backgroundColorByName("red"); + +Supported color names are: + + black, darkGray, lightGray, white, gray, red, green, blue, cyan, yellow, magenta, orange, purple, brown + + +Supported Platforms +------------------- + +- iOS +- Android 5+ +- Windows Phone 7 +- Windows Phone 8 +- Windows Phone 8.1 + +StatusBar.backgroundColorByHexString +================= + +Sets the background color of the statusbar by a hex string. + + StatusBar.backgroundColorByHexString("#C0C0C0"); + +CSS shorthand properties are also supported. + + StatusBar.backgroundColorByHexString("#333"); // => #333333 + StatusBar.backgroundColorByHexString("#FAB"); // => #FFAABB + +On iOS 7, when you set StatusBar.statusBarOverlaysWebView to false, you can set the background color of the statusbar by a hex string (#RRGGBB). + +On WP7 and WP8 you can also specify values as #AARRGGBB, where AA is an alpha value + +Supported Platforms +------------------- + +- iOS +- Android 5+ +- Windows Phone 7 +- Windows Phone 8 +- Windows Phone 8.1 + +StatusBar.hide +================= + +Hide the statusbar. + + StatusBar.hide(); + + +Supported Platforms +------------------- + +- iOS +- Android +- Windows Phone 7 +- Windows Phone 8 +- Windows Phone 8.1 + +StatusBar.show +================= + +Shows the statusbar. + + StatusBar.show(); + + +Supported Platforms +------------------- + +- iOS +- Android +- Windows Phone 7 +- Windows Phone 8 +- Windows Phone 8.1 + + +StatusBar.isVisible +================= + +Read this property to see if the statusbar is visible or not. + + if (StatusBar.isVisible) { + // do something + } + + +Supported Platforms +------------------- + +- iOS +- Android +- Windows Phone 7 +- Windows Phone 8 +- Windows Phone 8.1 + + diff --git a/doc/index.md b/doc/index.md deleted file mode 100644 index d22662c..0000000 --- a/doc/index.md +++ /dev/null @@ -1,294 +0,0 @@ - -# org.apache.cordova.statusbar - -StatusBar -====== - -> The `StatusBar` object provides some functions to customize the iOS and Android StatusBar. - - -## Installation - - cordova plugin add org.apache.cordova.statusbar - -Preferences ------------ - -#### config.xml - -- __StatusBarOverlaysWebView__ (boolean, defaults to true). On iOS 7, make the statusbar overlay or not overlay the WebView at startup. - - - -- __StatusBarBackgroundColor__ (color hex string, defaults to #000000). On iOS 7 and Android 5, set the background color of the statusbar by a hex string (#RRGGBB) at startup. - - - -- __StatusBarStyle__ (status bar style, defaults to lightcontent). On iOS 7, set the status bar style. Available options default, lightcontent, blacktranslucent, blackopaque. - - - -### Android Quirks -The 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: -```js -if (cordova.platformId == 'android') { - StatusBar.backgroundColorByHexString("#333"); -} -``` - -Hiding at startup ------------ - -During 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. - -Add/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: - - - UIStatusBarHidden - - UIViewControllerBasedStatusBarAppearance - - - -Methods -------- -This plugin defines global `StatusBar` object. - -Although in the global scope, it is not available until after the `deviceready` event. - - document.addEventListener("deviceready", onDeviceReady, false); - function onDeviceReady() { - console.log(StatusBar); - } - -- StatusBar.overlaysWebView -- StatusBar.styleDefault -- StatusBar.styleLightContent -- StatusBar.styleBlackTranslucent -- StatusBar.styleBlackOpaque -- StatusBar.backgroundColorByName -- StatusBar.backgroundColorByHexString -- StatusBar.hide -- StatusBar.show - -Properties --------- - -- StatusBar.isVisible - -Permissions ------------ - -#### config.xml - - - - - -StatusBar.overlaysWebView -================= - -On iOS 7, make the statusbar overlay or not overlay the WebView. - - StatusBar.overlaysWebView(true); - -Description ------------ - -On 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. - - -Supported Platforms -------------------- - -- iOS - -Quick Example -------------- - - StatusBar.overlaysWebView(true); - StatusBar.overlaysWebView(false); - -StatusBar.styleDefault -================= - -Use the default statusbar (dark text, for light backgrounds). - - StatusBar.styleDefault(); - - -Supported Platforms -------------------- - -- iOS -- Windows Phone 7 -- Windows Phone 8 -- Windows Phone 8.1 - -StatusBar.styleLightContent -================= - -Use the lightContent statusbar (light text, for dark backgrounds). - - StatusBar.styleLightContent(); - - -Supported Platforms -------------------- - -- iOS -- Windows Phone 7 -- Windows Phone 8 -- Windows Phone 8.1 - -StatusBar.styleBlackTranslucent -================= - -Use the blackTranslucent statusbar (light text, for dark backgrounds). - - StatusBar.styleBlackTranslucent(); - - -Supported Platforms -------------------- - -- iOS -- Windows Phone 7 -- Windows Phone 8 -- Windows Phone 8.1 - -StatusBar.styleBlackOpaque -================= - -Use the blackOpaque statusbar (light text, for dark backgrounds). - - StatusBar.styleBlackOpaque(); - - -Supported Platforms -------------------- - -- iOS -- Windows Phone 7 -- Windows Phone 8 -- Windows Phone 8.1 - - -StatusBar.backgroundColorByName -================= - -On iOS 7, when you set StatusBar.statusBarOverlaysWebView to false, you can set the background color of the statusbar by color name. - - StatusBar.backgroundColorByName("red"); - -Supported color names are: - - black, darkGray, lightGray, white, gray, red, green, blue, cyan, yellow, magenta, orange, purple, brown - - -Supported Platforms -------------------- - -- iOS -- Android 5+ -- Windows Phone 7 -- Windows Phone 8 -- Windows Phone 8.1 - -StatusBar.backgroundColorByHexString -================= - -Sets the background color of the statusbar by a hex string. - - StatusBar.backgroundColorByHexString("#C0C0C0"); - -CSS shorthand properties are also supported. - - StatusBar.backgroundColorByHexString("#333"); // => #333333 - StatusBar.backgroundColorByHexString("#FAB"); // => #FFAABB - -On iOS 7, when you set StatusBar.statusBarOverlaysWebView to false, you can set the background color of the statusbar by a hex string (#RRGGBB). - -On WP7 and WP8 you can also specify values as #AARRGGBB, where AA is an alpha value - -Supported Platforms -------------------- - -- iOS -- Android 5+ -- Windows Phone 7 -- Windows Phone 8 -- Windows Phone 8.1 - -StatusBar.hide -================= - -Hide the statusbar. - - StatusBar.hide(); - - -Supported Platforms -------------------- - -- iOS -- Android -- Windows Phone 7 -- Windows Phone 8 -- Windows Phone 8.1 - -StatusBar.show -================= - -Shows the statusbar. - - StatusBar.show(); - - -Supported Platforms -------------------- - -- iOS -- Android -- Windows Phone 7 -- Windows Phone 8 -- Windows Phone 8.1 - - -StatusBar.isVisible -================= - -Read this property to see if the statusbar is visible or not. - - if (StatusBar.isVisible) { - // do something - } - - -Supported Platforms -------------------- - -- iOS -- Android -- Windows Phone 7 -- Windows Phone 8 -- Windows Phone 8.1 - -