Skip to content

Commit 0e2118b

Browse files
stevengillpurplecabbage
stevengill
authored and
purplecabbage
committed
Version 3.4.0
1 parent 748f671 commit 0e2118b

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

59 files changed

+9967
-0
lines changed

‎docs/en/3.4.0/config.json‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{
2+
"language": "English",
3+
"merge": {
4+
"events.md": [
5+
"cordova/events/events.md",
6+
"cordova/events/events.deviceready.md",
7+
"cordova/events/events.pause.md",
8+
"cordova/events/events.resume.md",
9+
"cordova/events/events.backbutton.md",
10+
"cordova/events/events.menubutton.md",
11+
"cordova/events/events.searchbutton.md",
12+
"cordova/events/events.startcallbutton.md",
13+
"cordova/events/events.endcallbutton.md",
14+
"cordova/events/events.volumedownbutton.md",
15+
"cordova/events/events.volumeupbutton.md"
16+
]
17+
}
18+
}

‎docs/en/3.4.0/config_ref/images.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
---
2+
license: Licensed to the Apache Software Foundation (ASF) under one
3+
or more contributor license agreements. See the NOTICE file
4+
distributed with this work for additional information
5+
regarding copyright ownership. The ASF licenses this file
6+
to you under the Apache License, Version 2.0 (the
7+
"License"); you may not use this file except in compliance
8+
with the License. You may obtain a copy of the License at
9+
10+
http://www.apache.org/licenses/LICENSE-2.0
11+
12+
Unless required by applicable law or agreed to in writing,
13+
software distributed under the License is distributed on an
14+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
KIND, either express or implied. See the License for the
16+
specific language governing permissions and limitations
17+
under the License.
18+
---
19+
20+
# Icons and Splash Screens
21+
22+
This section shows how to configure an app's icon and optional splash
23+
screen for various platforms, both when working in the Cordova CLI
24+
(described in The Command-Line Interface) or using platform-specific
25+
SDK tools (detailed in the Platform Guides).
26+
27+
## Configuring Icons in the CLI
28+
29+
When working in the CLI, icon source files are located within various
30+
platform-specific subdirectories within the project's `www/res/icons`
31+
directory. Newly created projects come with a default set of Cordova
32+
icons for you to replace for the platforms you wish to target.
33+
34+
Android specifies icons for low, medium, high, and extra-high resolutions:
35+
36+
android/icon-36-ldpi.png
37+
android/icon-48-mdpi.png
38+
android/icon-72-hdpi.png
39+
android/icon-96-xhdpi.png
40+
41+
The iOS platform specifies 72-pixel-square icons for iPads, and
42+
57-pixel icons for iPhones and iPods, with high-resolution _2x_
43+
variants for retina displays:
44+
45+
ios/icon-57-2x.png
46+
ios/icon-57.png
47+
ios/icon-72-2x.png
48+
ios/icon-72.png
49+
50+
Windows Phone specifies a default 48-pixel icon, along with various
51+
devices' background tiling images used when representing applications:
52+
53+
windows-phone/icon-48.png
54+
windows-phone/icon-62-tile.png
55+
windows-phone/icon-173-tile.png
56+
57+
Blackberry 10 requires an icon element in config.xml:
58+
59+
<icon src="blackberry10/icon-86.png" />
60+
61+
See BlackBerry's documentation for targeting multiple sizes and locales.
62+
63+
[http://developer.blackberry.com/html5/documentation/icon_element.html]
64+
65+
Tizen requires an 128-pixel icon:
66+
67+
tizen/icon-128.png
68+
69+
## Configuring Splash Screens in the CLI
70+
71+
Use the Splashscreen API to enable display of an app's introductory
72+
splash screen on many platforms. When working in the CLI, splash
73+
screen source files are located within the project's `www/res/screens`
74+
subdirectory.
75+
76+
Android specifies both portrait- and landscape-oriented splash screen
77+
images for low, medium, high, and extra-high resolutions:
78+
79+
android/screen-hdpi-landscape.png
80+
android/screen-hdpi-portrait.png
81+
android/screen-ldpi-landscape.png
82+
android/screen-ldpi-portrait.png
83+
android/screen-mdpi-landscape.png
84+
android/screen-mdpi-portrait.png
85+
android/screen-xhdpi-landscape.png
86+
android/screen-xhdpi-portrait.png
87+
88+
The iOS platform specifies variants for iPhone/iPod and iPad, with
89+
variants for retina displays and different orientations. The _568h_
90+
file applies to the iPhone 5's taller screen:
91+
92+
ios/screen-ipad-landscape-2x.png
93+
ios/screen-ipad-landscape.png
94+
ios/screen-ipad-portrait-2x.png
95+
ios/screen-ipad-portrait.png
96+
ios/screen-iphone-landscape-2x.png
97+
ios/screen-iphone-landscape.png
98+
ios/screen-iphone-portrait-2x.png
99+
ios/screen-iphone-portrait.png
100+
ios/screen-iphone-portrait-568h-2x.png
101+
102+
Windows Phone specifies a single splash screen image:
103+
104+
windows-phone/screen-portrait.jpg
105+
106+
The following sections detail how to set up splash screens when
107+
working with SDKs and related command-line tools described in Platform
108+
Guides.
109+
110+
Don't forget to install the SplashScreen plugin before trying to use the
111+
`navigator.splashscreen.hide()` or `navigator.splashscreen.show()` methods.
112+
113+
## Splash Screens for the Android Platform
114+
115+
Place [9-patch image](https://developer.android.com/tools/help/draw9patch.html)
116+
files in the Android project's `platforms/android/res/drawable*` directories.
117+
118+
The size for each should be:
119+
120+
- xlarge (xhdpi): at least 960 &times; 720
121+
- large (hdpi): at least 640 &times; 480
122+
- medium (mdpi): at least 470 &times; 320
123+
- small (ldpi): at least 426 &times; 320
124+
125+
When creating a new Android project, the default splash screen images
126+
provided in the Cordova sample app should already be present in the
127+
`platforms/android/res/drawable*` directories. Feel free to replace these
128+
with your own images.
129+
When providing your own splash screen images, you do not need to
130+
provide the same permutation of 8 as the Cordova default ones
131+
here. More or less optimization can be used.
132+
The `drawable` directory names must follow the Android conventions for
133+
supporting
134+
[screen sizes](http://developer.android.com/guide/practices/screens_support.html) and
135+
[alternate resources](http://developer.android.com/guide/topics/resources/providing-resources.html#AlternativeResources).
136+
137+
In the top-level `config.xml` file (not the one in `platforms`), add the
138+
following preferences:
139+
140+
<preference name="SplashScreen" value="screen" />
141+
<preference name="SplashScreenDelay" value="10000" />
142+
143+
The first line sets the image to display as the splash screen. This is the
144+
file name of the png in the `drawable*` directories, minus the `.png`
145+
extension. The default value for SplashScreen is `screen` (for the file
146+
`platforms/android/res/drawable*/screen.png`), so if you
147+
name the image anything other than `screen.png` in the `drawable*` directories,
148+
you need to add/modify this line.
149+
150+
The second line sets the default delay of how long the splashscreen appears in
151+
milliseconds. This should be the worst-case expected start time.
152+
The default value for SplashScreenDelay is 3000 ms.
153+
154+
Finally, as a best practice, the splash screen should be present only as long
155+
as necessary. When your app has started and the webview has loaded, your app
156+
should hide the splash screen so that your main view is visible as soon as it
157+
is ready. Because the app start time will vary quite a bit due to a number of
158+
factors such as CPU speed and network, it is recommended that your app
159+
explicitly invoke `navigator.splashscreen.hide()` in the JavaScript
160+
method that responds to the `deviceready` event. Otherwise the splash screen
161+
will be visible for the SplashScreenDelay value that you configured above,
162+
which is likely longer than necessary.
163+
This event-driven approach is highly recommended versus having the splash
164+
screen visible for always a fixed duration.
165+
166+
## Splash Screens for the iOS Platform
167+
168+
Copy splash screen images into the iOS project's `Resources/splash`
169+
directory. Only add those images for the devices you want to support,
170+
such as iPad or iPhone. The size of each image should be:
171+
172+
- Default-568h@2x~iphone.png (640x1136 pixels)
173+
- Default-Landscape@2x~ipad.png (2048x1496 pixels)
174+
- Default-Landscape~ipad.png (1024x748 pixels)
175+
- Default-Portrait@2x~ipad.png (1536x2008 pixels)
176+
- Default-Portrait~ipad.png (768x1004 pixels)
177+
- Default@2x~iphone.png (640x960 pixels)
178+
- Default~iphone.png (320x480 pixels)
179+
180+
## Splash Screens for the BlackBerry 10 Platform
181+
182+
Add a rim:splash element to config.xml for each resolution and locale you wish
183+
to support:
184+
185+
<http://developer.blackberry.com/html5/documentation/rim_splash_element.html>

‎docs/en/3.4.0/config_ref/index.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
---
2+
license: Licensed to the Apache Software Foundation (ASF) under one
3+
or more contributor license agreements. See the NOTICE file
4+
distributed with this work for additional information
5+
regarding copyright ownership. The ASF licenses this file
6+
to you under the Apache License, Version 2.0 (the
7+
"License"); you may not use this file except in compliance
8+
with the License. You may obtain a copy of the License at
9+
10+
http://www.apache.org/licenses/LICENSE-2.0
11+
12+
Unless required by applicable law or agreed to in writing,
13+
software distributed under the License is distributed on an
14+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
KIND, either express or implied. See the License for the
16+
specific language governing permissions and limitations
17+
under the License.
18+
---
19+
20+
# The config.xml File
21+
22+
Many aspects of an app's behavior can be controlled with a global
23+
configuration file, `config.xml`. This
24+
platform-agnostic XML file is arranged based on the W3C's [Packaged
25+
Web Apps (Widgets)](http://www.w3.org/TR/widgets/) specification, and
26+
extended to specify core Cordova API features, plugins, and
27+
platform-specific settings.
28+
29+
For projects created with the Cordova CLI (described in The
30+
Command-Line Interface), this file can be found in the top-level
31+
directory:
32+
33+
app/config.xml
34+
35+
Note that before version 3.3.1-0.2.0, the file existed at `app/www/config.xml`,
36+
and that having it here is still supported.
37+
38+
When using the CLI to build a project, versions of this file are
39+
passively copied into various `platforms/` subdirectories, for example:
40+
41+
app/platforms/ios/AppName/config.xml
42+
app/platforms/blackberry10/www/config.xml
43+
app/platforms/android/res/xml/config.xml
44+
45+
This section details global and cross-platform configuration options.
46+
See the following sections for platform-specific options:
47+
48+
- iOS Configuration
49+
- Android Configuration
50+
- BlackBerry 10 Configuration
51+
52+
In addition to the various configuration options detailed below, you
53+
can also configure an application's core set of images for each target
54+
platform. See Icons and Splash Screens for more information.
55+
56+
## Core Configuration Elements
57+
58+
This example shows the default `config.xml` generated by the CLI's
59+
`create` command, described in The Command-Line Interface:
60+
61+
<widget id="com.example.hello" version="0.0.1">
62+
<name>HelloWorld</name>
63+
<description>
64+
A sample Apache Cordova application that responds to the deviceready event.
65+
</description>
66+
<author email="[email protected]" href="http://cordova.io">
67+
Apache Cordova Team
68+
</author>
69+
<content src="index.html" />
70+
<access origin="*" />
71+
</widget>
72+
73+
The following configuration elements appear in the top-level
74+
`config.xml` file, and are supported across all supported Cordova
75+
platforms:
76+
77+
- The `<widget>` element's `id` attribute provides the app's
78+
reverse-domain identifier, and the `version` its full version number
79+
expressed in major/minor/patch notation.
80+
81+
- The `<name>` element specifies the app's formal name, as it appears
82+
on the device's home screen and within app-store interfaces.
83+
84+
- The `<description>` and `<author>` elements specify metadata and
85+
contact information that may appear within app-store listings.
86+
87+
- The optional `<content>` element defines the app's starting
88+
page in the top-level web assets directory. The default value is
89+
`index.html`, which customarily appears in a project's top-level
90+
`www` directory.
91+
92+
- `<access>` elements define the set of external domains the app is
93+
allowed to communicate with. The default value shown above allows
94+
it to access any server. See the Domain Whitelist Guide for details.
95+
96+
- The `<preference>` tag sets various options as pairs of
97+
`name`/`value` attributes. Each preference's `name` is
98+
case-insensitive. Many preferences are unique to specific
99+
platforms, as listed at the top of this page. The following sections
100+
detail preferences that apply to more than one platform.
101+
102+
## Global Preferences
103+
104+
The following global preferences apply to all platforms:
105+
106+
- `Fullscreen` allows you to hide the status bar at the top of the
107+
screen. The default value is `false`. Example:
108+
109+
<preference name="Fullscreen" value="true" />
110+
111+
- `Orientation` allows you to lock orientation and prevent the
112+
interface from rotating in response to changes in orientation.
113+
Possible values are `default`, `landscape`, or `portrait`. Example:
114+
115+
<preference name="Orientation" value="landscape" />
116+
117+
__NOTE__: The `default` value means _both_ landscape and portrait
118+
orientations are enabled. If you want to use each platform's
119+
default settings (usually portrait-only), leave this tag out of the
120+
`config.xml` file.
121+
122+
## Multi-Platform Preferences
123+
124+
The following preferences apply to more than one platform, but not to
125+
all of them:
126+
127+
- `DisallowOverscroll` (boolean, defaults to `false`): set to `true`
128+
if you don't want the interface to display any feedback when users
129+
scroll past the beginning or end of content.
130+
131+
<preference name="DisallowOverscroll" value="true"/>
132+
133+
Applies to Android and iOS. On iOS, overscroll gestures cause
134+
content to bounce back to its original position. On Android, they
135+
produce a more subtle glowing effect along the top or bottom edge of
136+
the content.
137+
138+
- `BackgroundColor`: Set the app's background color. Supports a
139+
four-byte hex value, with the first byte representing the alpha
140+
channel, and standard RGB values for the following three bytes. This
141+
example specifies blue:
142+
143+
<preference name="BackgroundColor" value="0xff0000ff"/>
144+
145+
Applies to Android and BlackBerry. Overrides CSS otherwise available
146+
across _all_ platforms, for example: `body{background-color:blue}`.
147+
148+
- `HideKeyboardFormAccessoryBar` (boolean, defaults to `false`): set
149+
to `true` to hide the additional toolbar that appears above the
150+
keyboard, helping users navigate from one form input to another.
151+
152+
<preference name="HideKeyboardFormAccessoryBar" value="true"/>
153+
154+
Applies to iOS and BlackBerry.
155+
156+
## The _feature_ Element
157+
158+
If you use the CLI to build applications, you use the `plugin` command
159+
to enable device APIs. This does not modify the top-level `config.xml`
160+
file, so the `<feature>` element does not apply to your workflow. If
161+
you work directly in an SDK and using the platform-specific
162+
`config.xml` file as source, you use the `<feature>` tag to enable
163+
device-level APIs and external plugins. They often appear with custom values in
164+
platform-specific `config.xml` files. For example, here is how to specify the
165+
Device API for Android projects:
166+
167+
<feature name="Device">
168+
<param name="android-package" value="org.apache.cordova.device.Device" />
169+
</feature>
170+
171+
Here is how the element appears for iOS projects:
172+
173+
<feature name="Device">
174+
<param name="ios-package" value="CDVDevice" />
175+
</feature>
176+
177+
See the API Reference for details on how to specify each feature. See
178+
the Plugin Development Guide for more information on plugins.

0 commit comments

Comments
 (0)