pdk/docs/guide/customization.jd

   1 page.title=Customization
   2 pdk.version=1.0
   3 @jd:body
   4
   5 <div id="qv-wrapper">
   6 <div id="qv">
   7 <h2>In this document</h2>
   8 <a name="toc"/>
   9 <ul>
  10 <li><a href="#androidBootScreenCustomization">Boot Screen Customization</a></li>
  11 <li><a href="#androidNetCustPlat">Network Customization Platform</a></li>
  12 <li><a href="#androidCustomizingPre-LoadedApps">Customizing pre-loaded applications</a></li>
  13 <li><a href="#androidBrowserBookmarks">Customizing browser bookmarks</a></li>
  14 <li><a href="#androidEmailProviderCustomization">Email Provider Customization</a></li>
  15 <li><a href="#androidThemes">Platform Themes</a></li>
  16 </ul>
  17 </div>
  18 </div>
  19
  20
  21
  22 <a name="androidBootScreenCustomization"></a><h3>Boot Screen Customization</h3>
  23
  24 <p>At startup, Android displays a splashscreen image while booting the device. Do the following if you wish to modify the default splash screen:</p>
  25 <p>
  26 <ol><li>Create a 320x480 image, <code>splashscreen.jpg</code> in this example.</li>
  27 <li>Using ImageMagick, convert your .jpg file to .r format:
  28 <pre class="prettify">
  29 convert screen.jpg screen.r
  30 </pre>
  31 </li>
  32 <li>Use the rgb2565 application to convert the image to 565 format:
  33 <pre class="prettify">
  34 rgb2565 < screen.rgb > screen.565
  35 </pre>
  36 </li>
  37 <li>Use fastboot to flash the image to the device:
  38 <pre class="prettify">
  39 fastboot flash splash1 screen.565
  40 </pre>
  41 </li>
  42 </ol>
  43
  44
  45 <a name="androidNetCustPlat"></a><h3>Network Customization Platform</h3>
  46
  47
  48
  49 <a name="androidNetCustPlatNetworkConfig"></a><h4>Network Configuration</h4>
  50
  51 <p>Android stores network configurations as a resource that gets compiled into binary at form at build time. The XML representation of this resource is located at <code>//android/frameworks/base/core/res/res/xml/apns.xml</code>. This file does not include any configured APNs. You should not modify this file, but instead configure APNs by product at build time (see Build-time APN Configuration below).</p>
  52 <p>Each network configuration is stored in an XML element following this syntax:</p>
  53 <pre class="prettify">
  54 &lt;apn carrier="T-Mobile US"
  55          mcc="310"
  56          mnc="260"
  57          apn=" wap.voicestream.com"
  58          user="none"
  59          server="*"
  60          password="none"
  61          proxy=" 216.155.165.50"
  62          port="8080"
  63          mmsc="http://216.155.174.84/servlets/mms"
  64 /&gt;
  65 </pre>
  66
  67
  68 <a name="androidNetCustPlatAPNConfig"></a><h4>Build-time APN configuration</h4>
  69
  70 <p>To set the APN configuration for a particular product target, add an <code>apns-conf.xml</code> file to the product configuration (do not modify the default platform APNs). This allows multiple products, all with different APNs, to be built off the same code base.  </p>
  71
  72 <p>To configure APNs at the product level, add a line to the product configuration file like the example below (<code>vendor/&lt;vendor_name&gt;/products/myphone-us.mk</code>): </p>
  73
  74 <pre class="prettify">
  75 PRODUCT_COPY_FILES := vendor/acme/etc/apns-conf-us.xml:system/etc/apns-conf.xml
  76 </pre>
  77
  78
  79
  80 <a name="androidNetCustPlatAPNRunTime"></a><h4>APN configuration at run time</h4>
  81
  82 <p>At runtime, the Android reads APNs from the following file:</p>
  83 <pre class="prettify">
  84 system/etc/apns-conf.xml
  85 </pre>
  86
  87 <p>Android supports the following run-time network configuration methods to choose the appropriate APN from the list of configured APNs:</p>
  88 <p><ul>
  89 <li><b>Automatic Configuration</b>: At boot time, Android determines the correct network configuration based on the MCC and MNC from the SIM card and automatically configure all network settings.</li>
  90 <li><b>Manual Configuration</b>: The platform will also support runtime (user) manual selection of network settings by name, for example, "Company Name US," and will support manual network configuration entry.</li>
  91 <li><b>WAP / SMS Push Configuration</b>: The network configurations are standard Android resources. You can upgrade a resource at runtime by installing a new system resource APK package. It will be possible to develop a network configuration service which listens to a specific binary SMS port for binary SMS messages containing the network configurations.  NOTE: The implementation will likely be network operator dependent due to inconsistent SMS ports, binary SMS formats, etc.</li>
  92 </ul>
  93
  94
  95
  96
  97 <a name="androidCustomizingPre-LoadedApps"></a><h3>Customizing pre-loaded applications</h3>
  98
  99 <p>To customize the list of Android packages for a particular product (applications, input methods, providers, services, etc.), set <code>PRODUCT_PACKAGES</code> property in the product configuration, as illustrated below:</p>
 100
 101 <pre class="prettify">
 102 PRODUCT_PACKAGES := \
 103  &lt;company_name&gt;Mail \
 104     &lt;company_name&gt;IM \
 105  &lt;company_name&gt;HomeScreen \
 106  &lt;company_name&gt;Maps \
 107  &lt;company_name&gt;SystemUpdater
 108 </pre>
 109
 110 <p>Package names should correspond to the <code>LOCAL_PACKAGE_NAME</code> specified for each package's build target. For example, the <code>Android.mk</code> build target for &lt;company_name&gt;Mail, referenced above, could look like this:
 111
 112 <pre class="prettify">
 113 # Build the &lt;company_name&gt;Mail application
 114 LOCAL_PATH:= $(call my-dir)
 115 include $(CLEAR_VARS)
 116
 117 LOCAL_MODULE_TAGS := user development
 118
 119 LOCAL_SRC_FILES := $(call all-java-files-under,src,tests)
 120
 121 LOCAL_STATIC_JAVA_LIBRARIES := &lt;company_name&gt;login-client
 122
 123 # Specify the package name
 124 LOCAL_PACKAGE_NAME := &lt;company_name&gt;Mail
 125
 126 # Specify the certificate used to sign the application
 127 LOCAL_CERTIFICATE := vendor/&lt;company_name&gt;/certs/app
 128
 129 include $(BUILD_PACKAGE)
 130
 131 # Build the login client static library
 132 include $(LOCAL_PATH)/client/Android.mk
 133 </pre>
 134
 135 <p>Note that the home screen is just an Android application that can be replaced entirely or customized by changing source code and application resources (Java source, layouts, etc.).</p>
 136
 137
 138
 139 <a name="androidBrowserBookmarks"></a><h3>Customizing browser bookmarks</h3>
 140
 141 <p>Browser bookmarks are stored as string resources in the Browser application: <code>//android/packages/apps/Browser/res/values/strings.xml</code>.  Bookmarks are defined as simple value string arrays called &quot;bookmarks&quot;.  Each bookmark entry is stored as a pair of array values; the first represents the bookmark name and the second the bookmark URL.  For example:</p>
 142 <pre class="prettify">
 143 &lt;!-- Bookmarks --&gt;
 144 &lt;string-array name=&quot;bookmarks&quot;&gt;
 145     &lt;item&gt;Google&lt;/item&gt;
 146     &lt;item&gt;http://www.google.com/&lt;/item&gt;
 147     &lt;item&gt;Yahoo!&lt;/item&gt;
 148     &lt;item&gt;http://www.yahoo.com/&lt;/item&gt;
 149     &lt;item&gt;MSN&lt;/item&gt;
 150     &lt;item&gt;http://www.msn.com/&lt;/item&gt;
 151     &lt;item&gt;MySpace&lt;/item&gt;
 152     &lt;item&gt;http://www.myspace.com/&lt;/item&gt;
 153     &lt;item&gt;Facebook&lt;/item&gt;
 154     &lt;item&gt;http://www.facebook.com/&lt;/item&gt;
 155     &lt;item&gt;Wikipedia&lt;/item&gt;
 156     &lt;item&gt;http://www.wikipedia.org/&lt;/item&gt;
 157     &lt;item&gt;eBay&lt;/item&gt;
 158     &lt;item&gt;http://www.ebay.com/&lt;/item&gt;
 159     &lt;item&gt;CNN&lt;/item&gt;
 160     &lt;item&gt;http://www.cnn.com/&lt;/item&gt;
 161     &lt;item&gt;New York Times&lt;/item&gt;
 162     &lt;item&gt;http://www.nytimes.com/&lt;/item&gt;
 163     &lt;item&gt;ESPN&lt;/item&gt;
 164     &lt;item&gt;http://espn.go.com/&lt;/item&gt;
 165     &lt;item&gt;Amazon&lt;/item&gt;
 166     &lt;item&gt;http://www.amazon.com/&lt;/item&gt;
 167     &lt;item&gt;Weather Channel&lt;/item&gt;
 168     &lt;item&gt;http://www.weather.com/&lt;/item&gt;
 169     &lt;item&gt;BBC&lt;/item&gt;
 170     &lt;item&gt;http://www.bbc.co.uk/&lt;/item&gt;
 171 &lt;/string-array&gt;
 172 </pre>
 173 <p>Like and Android application resource, the platform will load alternate resources based on the platform configuration values.  See <a href="http://developer.android.com/guide/topics/resources/resources-i18n.html">Resources and Internationalization</a> in the Android SDK for details.  To configure bookmarks for a specific mobile network operator, place your customized bookmarks in a separate <code>strings.xml</code> file and place it under a Mobile Network Code (MNO) specific resource folder.  For example, <code>Browser/res/values-mccXXX-mncYYY/strings.xml</code> where XXX and YYY represent the three-digit MCC and two to three digit MNC values.</p>
 174 <p>Android loads any configuration-specific resources as override values for the default values, so it is only necessary to include the bookmarks string-array values in this file.</p>
 175
 176
 177
 178 <a name="androidEmailProviderCustomization"></a>
 179 <h3>Email Provider Customization</h3>
 180
 181 <p>The default email provider settings are stored as string resources in the Email application (<code>//android/packages/apps/Email/res/xml/providers.xml</code>) as illustrated below.</p>
 182 <p>&lt;providers&gt;</p>
 183 <pre class="prettify">
 184 &lt;!-- Gmail variants --&gt;
 185     &lt;provider id=&quot;gmail&quot; label=&quot;Gmail&quot; domain=&quot;gmail.com&quot;&gt;
 186         &lt;incoming uri=&quot;imap+ssl+://imap.gmail.com&quot; username=&quot;$email&quot;/&gt;
 187         &lt;outgoing uri=&quot;smtp+ssl+://smtp.gmail.com&quot; username=&quot;$email&quot;/&gt;
 188     &lt;/provider&gt;
 189     &lt;provider id=&quot;googlemail&quot; label=&quot;Google Mail&quot; domain=&quot;googlemail.com&quot;&gt;
 190         &lt;incoming uri=&quot;imap+ssl+://imap.googlemail.com&quot; username=&quot;$email&quot;/&gt;
 191         &lt;outgoing uri=&quot;smtp+ssl+://smtp.googlemail.com&quot; username=&quot;$email&quot;/&gt;
 192     &lt;/provider&gt;
 193     &lt;provider id=&quot;google&quot; label=&quot;Google&quot; domain=&quot;google.com&quot;&gt;
 194         &lt;incoming uri=&quot;imap+ssl+://imap.gmail.com&quot; username=&quot;$email&quot;/&gt;
 195         &lt;outgoing uri=&quot;smtp+ssl+://smtp.gmail.com&quot; username=&quot;$email&quot;/&gt;
 196     &lt;/provider&gt;
 197     &lt;provider id=&quot;android&quot; label=&quot;Android&quot; domain=&quot;android.com&quot;&gt;
 198         &lt;incoming uri=&quot;imap+ssl+://imap.gmail.com&quot; username=&quot;$email&quot;/&gt;
 199         &lt;outgoing uri=&quot;smtp+ssl+://smtp.gmail.com&quot; username=&quot;$email&quot;/&gt;
 200     &lt;/provider&gt;</p>
 201
 202     &lt;!-- Common US providers --&gt;
 203
 204     &lt;provider id=&quot;aim&quot; label=&quot;AIM&quot; domain=&quot;aim.com&quot;&gt;
 205         &lt;incoming uri=&quot;imap://imap.aim.com&quot; label=&quot;IMAP&quot; username=&quot;$email&quot;/&gt;
 206         &lt;outgoing uri=&quot;smtp://smtp.aim.com:587&quot; username=&quot;$email&quot;/&gt;
 207     &lt;/provider&gt;
 208     &lt;provider id=&quot;aol&quot; label=&quot;AOL&quot; domain=&quot;aol.com&quot;&gt;
 209         &lt;incoming uri=&quot;imap://imap.aol.com&quot; label=&quot;IMAP&quot; username=&quot;$email&quot;/&gt;
 210         &lt;outgoing uri=&quot;smtp://smtp.aol.com:587&quot; username=&quot;$email&quot;/&gt;
 211     &lt;/provider&gt;
 212     &lt;provider id=&quot;comcast&quot; label=&quot;Comcast&quot; domain=&quot;comcast.net&quot;&gt;
 213         &lt;incoming uri=&quot;pop3+ssl+://mail.comcast.net&quot; username=&quot;$user&quot;/&gt;
 214         &lt;outgoing uri=&quot;smtp+ssl+://smtp.comcast.net&quot; username=&quot;$user&quot;/&gt;
 215     &lt;/provider&gt;
 216     &lt;provider id=&quot;compuserve&quot; label=&quot;CompuServe&quot; domain=&quot;cs.com&quot;&gt;
 217         &lt;incoming uri=&quot;imap://imap.cs.com&quot; username=&quot;$user&quot;/&gt;
 218         &lt;outgoing uri=&quot;smtp://smtp.cs.com&quot; username=&quot;$user&quot;/&gt;
 219     &lt;/provider&gt;
 220     &lt;provider id=&quot;dotmac&quot; label=&quot;.Mac&quot; domain=&quot;mac.com&quot;&gt;
 221         &lt;incoming uri=&quot;imap+tls://mail.mac.com&quot; username=&quot;$email&quot;/&gt;
 222         &lt;outgoing uri=&quot;smtp+tls://smtp.mac.com&quot; username=&quot;$email&quot;/&gt;
 223     &lt;/provider&gt;
 224     &lt;provider id=&quot;earthlink&quot; label=&quot;Earthlink&quot; domain=&quot;earthlink.net&quot;&gt;
 225         &lt;incoming uri=&quot;pop3://pop.earthlink.net&quot; username=&quot;$email&quot;/&gt;
 226         &lt;outgoing uri=&quot;smtp://smtpauth.earthlink.net:587&quot; username=&quot;$email&quot;/&gt;
 227     &lt;/provider&gt;
 228     &lt;provider id=&quot;juno&quot; label=&quot;Juno&quot; domain=&quot;juno.com&quot;&gt;
 229         &lt;incoming uri=&quot;pop3://pop.juno.com&quot; username=&quot;$user&quot;/&gt;
 230         &lt;outgoing uri=&quot;smtp://smtp.juno.com&quot; username=&quot;$user&quot;/&gt;
 231     &lt;/provider&gt;
 232     &lt;provider id=&quot;live&quot; label=&quot;Windows Live Hotmail Plus&quot; domain=&quot;live.com&quot; note=&quot;@string/provider_note_live&quot;&gt;
 233         &lt;incoming uri=&quot;pop3+ssl+://pop3.live.com&quot; username=&quot;$email&quot;/&gt;
 234         &lt;outgoing uri=&quot;smtp+tls+://smtp.live.com&quot; username=&quot;$email&quot;/&gt;
 235     &lt;/provider&gt;
 236     &lt;provider id=&quot;hotmail&quot; label=&quot;Windows Live Hotmail Plus&quot; domain=&quot;hotmail.com&quot; note=&quot;@string/provider_note_live&quot;&gt;
 237         &lt;incoming uri=&quot;pop3+ssl+://pop3.live.com&quot; username=&quot;$email&quot;/&gt;
 238         &lt;outgoing uri=&quot;smtp+tls+://smtp.live.com&quot; username=&quot;$email&quot;/&gt;
 239     &lt;/provider&gt;
 240     &lt;provider id=&quot;msn&quot; label=&quot;Windows Live Hotmail Plus&quot; domain=&quot;msn.com&quot; note=&quot;@string/provider_note_live&quot;&gt;
 241         &lt;incoming uri=&quot;pop3+ssl+://pop3.live.com&quot; username=&quot;$email&quot;/&gt;
 242         &lt;outgoing uri=&quot;smtp+tls+://smtp.live.com&quot; username=&quot;$email&quot;/&gt;
 243     &lt;/provider&gt;
 244     &lt;provider id=&quot;mobileme&quot; label=&quot;MobileMe&quot; domain=&quot;me.com&quot;&gt;
 245         &lt;incoming uri=&quot;imap+tls://mail.me.com&quot; username=&quot;$email&quot;/&gt;
 246         &lt;outgoing uri=&quot;smtp+tls://smtp.me.com&quot; username=&quot;$email&quot;/&gt;
 247     &lt;/provider&gt;
 248     &lt;provider id=&quot;netzero&quot; label=&quot;NetZero&quot; domain=&quot;netzero.com&quot;&gt;
 249         &lt;incoming uri=&quot;pop3://pop.netzero.com&quot; username=&quot;$user&quot;/&gt;
 250         &lt;outgoing uri=&quot;smtp://smtp.netzero.com&quot; username=&quot;$user&quot;/&gt;
 251     &lt;/provider&gt;
 252     &lt;provider id=&quot;sbcglobal&quot; label=&quot;SBC Global&quot; domain=&quot;sbcglobal.net&quot;&gt;
 253         &lt;incoming uri=&quot;pop3://pop.sbcglobal.yahoo.com&quot; username=&quot;$email&quot;/&gt;
 254         &lt;outgoing uri=&quot;smtp://smtp.sbcglobal.yahoo.com&quot; username=&quot;$email&quot;/&gt;
 255     &lt;/provider&gt;
 256     &lt;provider id=&quot;verizon&quot; label=&quot;Verizon&quot; domain=&quot;verizon.net&quot;&gt;
 257         &lt;incoming uri=&quot;pop3://incoming.verizon.net&quot; username=&quot;$user&quot;/&gt;
 258         &lt;outgoing uri=&quot;smtp://outgoing.verizon.net&quot; username=&quot;$user&quot;/&gt;
 259     &lt;/provider&gt;
 260     &lt;provider id=&quot;yahoo&quot; label=&quot;Yahoo Plus&quot; domain=&quot;yahoo.com&quot; note=&quot;@string/provider_note_yahoo&quot;&gt;
 261         &lt;incoming uri=&quot;pop3+ssl+://plus.pop.mail.yahoo.com&quot; username=&quot;$user&quot;/&gt;
 262         &lt;outgoing uri=&quot;smtp+ssl+://plus.smtp.mail.yahoo.com&quot; username=&quot;$user&quot;/&gt;
 263     &lt;/provider&gt;
 264
 265     &lt;!-- Common UK providers --&gt;
 266
 267     &lt;provider id=&quot;aol-uk&quot; label=&quot;AOL&quot; domain=&quot;aol.co.uk&quot;&gt;
 268         &lt;incoming uri=&quot;imap+ssl+://imap.uk.aol.com&quot; label=&quot;IMAP&quot; username=&quot;$user&quot;/&gt;
 269         &lt;outgoing uri=&quot;smtp+ssl+://smtp.uk.aol.com&quot; username=&quot;$user&quot;/&gt;
 270     &lt;/provider&gt;
 271     &lt;provider id=&quot;bt&quot; label=&quot;BT Internet&quot; domain=&quot;btinternet.com&quot;&gt;
 272         &lt;incoming uri=&quot;pop3://mail.btinternet.com&quot; username=&quot;$email&quot;/&gt;
 273         &lt;outgoing uri=&quot;smtp://mail.btinternet.com&quot; username=&quot;&quot;/&gt;
 274     &lt;/provider&gt;
 275     &lt;provider id=&quot;tiscali&quot; label=&quot;Tiscali&quot; domain=&quot;tiscali.co.uk&quot;&gt;
 276         &lt;incoming uri=&quot;pop3://pop.tiscali.co.uk&quot; username=&quot;$email&quot;/&gt;
 277         &lt;outgoing uri=&quot;smtp://smtp.tiscali.co.uk&quot; username=&quot;$email:wq&quot;/&gt;
 278     &lt;/provider&gt;
 279     &lt;provider id=&quot;yahoo-uk&quot; label=&quot;Yahoo&quot; domain=&quot;yahoo.co.uk&quot; note=&quot;@string/provider_note_yahoo_uk&quot;&gt;
 280         &lt;incoming uri=&quot;pop3+ssl+://pop.mail.yahoo.co.uk&quot; username=&quot;$user&quot;/&gt;
 281         &lt;outgoing uri=&quot;smtp+ssl+://smtp.mail.yahoo.co.uk&quot; username=&quot;$user&quot;/&gt;
 282     &lt;/provider&gt;
 283
 284     &lt;!-- Common Germany providers --&gt;
 285
 286     &lt;provider id=&quot;freenet&quot; label=&quot;Freenet&quot; domain=&quot;freenet.de&quot;&gt;
 287         &lt;incoming uri=&quot;pop3://mx.freenet.de&quot; username=&quot;$user&quot;/&gt;
 288         &lt;outgoing uri=&quot;smtp+ssl://mx.freenet.de&quot; username=&quot;$email&quot;/&gt;
 289     &lt;/provider&gt;
 290     &lt;provider id=&quot;gmx&quot; label=&quot;GMX&quot; domain=&quot;gmx.de&quot;&gt;
 291         &lt;incoming uri=&quot;pop3+tls://pop.gmx.net&quot; username=&quot;$email&quot;/&gt;
 292         &lt;outgoing uri=&quot;smtp+tls://mail.gmx.net&quot; username=&quot;$email&quot;/&gt;
 293     &lt;/provider&gt;
 294     &lt;provider id=&quot;T-Online&quot; label=&quot;T-Online&quot; domain=&quot;t-online.de&quot; note=&quot;@string/provider_note_t_online&quot;&gt;
 295         &lt;incoming uri=&quot;pop3://popmail.t-online.de&quot; username=&quot;$email&quot;/&gt;
 296         &lt;outgoing uri=&quot;smtp://smtpmail.t-online.de&quot; username=&quot;$email&quot;/&gt;
 297     &lt;/provider&gt;
 298     &lt;provider id=&quot;web.de&quot; label=&quot;Web.de&quot; domain=&quot;web.de&quot;&gt;
 299         &lt;incoming uri=&quot;pop3+tls://pop3.web.de&quot; username=&quot;$user&quot;/&gt;
 300         &lt;outgoing uri=&quot;smtp+tls://smtp.web.de&quot; username=&quot;$user&quot;/&gt;
 301     &lt;/provider&gt;
 302 &lt;/providers&gt;
 303 </pre>
 304 <p>As with all Android application resources, the platform will load alternate resources based on the platform configuration values.  See <a href="http://developer.android.com/guide/topics/resources/resources-i18n.html">Resources and Internationalization</a> in the Android SDK for details.  To configure email providers for a specific mobile network operator, place the customized providers in a separate <code>providers.xml</code> file and place it under  a Mobile Network Code (MNO) specific resource folder.  For example, <code>Email/res/xml-mccXXX-mncYYY/providers.xml</code> where XXX and YYY represent the three-digit MCC and two to three digit MNC values.</p>
 305
 306
 307
 308 <a name="androidThemes"></a><h3>Platform Themes</h3>
 309
 310
 311
 312 <a name="androidThemesStyles"></a><h4>Themes and Styles</h4>
 313
 314 <p>System level styles are defined in <code>//android/framework/base/core/res/res/values/styles.xml</code>.</p>
 315
 316
 317 <a name="androidThemesAnimations"></a><h4>Animations</h4>
 318
 319 <p>Android supports configurable animations for window and view transitions.  System-level animations are defined in XML in global resource files located in <code>//android/framework/base/core/res/res/anim/</code>.</p>
 320