diff --git a/docs/html/guide/appendix/glossary.jd b/docs/html/guide/appendix/glossary.jd old mode 100644 new mode 100755 index db518f9318790..a200a6c0ff0e5 --- a/docs/html/guide/appendix/glossary.jd +++ b/docs/html/guide/appendix/glossary.jd @@ -41,8 +41,8 @@ excludeFromSuggestions=true
adb
Android Debug Bridge, a command-line debugging application included with the SDK. It provides tools to browse the device, copy tools on the device, and - forward ports for debugging. If you are developing in Eclipse using the - ADT Plugin, adb is integrated into your development environment. See + forward ports for debugging. If you are developing in Android Studio, + adb is integrated into your development environment. See Android Debug Bridge for more information.
@@ -90,8 +90,8 @@ excludeFromSuggestions=true
DDMS
Dalvik Debug Monitor Service, a GUI debugging application included with the SDK. It provides screen capture, log dump, and process - examination capabilities. If you are developing in Eclipse using the ADT - Plugin, DDMS is integrated into your development environment. See Using DDMS to learn more about the program.
Dialog
A floating window that acts as a lightweight @@ -290,4 +290,4 @@ excludeFromSuggestions=true in your application.
- \ No newline at end of file + diff --git a/docs/html/guide/practices/seamlessness.jd b/docs/html/guide/practices/seamlessness.jd old mode 100644 new mode 100755 index 9679e2a8a2cee..347e457bd24e4 --- a/docs/html/guide/practices/seamlessness.jd +++ b/docs/html/guide/practices/seamlessness.jd @@ -209,8 +209,8 @@ likely to be unpopular.

you're using the emulator, since the emulator uses your desktop computer's network connection. That's almost guaranteed to be much faster than a cell network, so you'll want to change the settings on the emulator that simulate -slower network speeds. You can do this in Eclipse, in the "Emulator Settings" -tab of your launch configuration or via a command-line option when starting the emulator.

diff --git a/docs/html/guide/topics/connectivity/sip.jd b/docs/html/guide/topics/connectivity/sip.jd old mode 100644 new mode 100755 index 5154767e16ade..d754894741e7f --- a/docs/html/guide/topics/connectivity/sip.jd +++ b/docs/html/guide/topics/connectivity/sip.jd @@ -478,14 +478,19 @@ wireless, so you must test on an actual device. Testing on AVD won't work.
  1. On your device, connect to wireless (Settings > Wireless & networks -> Wi-Fi > Wi-Fi settings)
    2. +> Wi-Fi > Wi-Fi settings).
  2. Set up your mobile device for testing, as described in Developing on a Device.
  3. Run your application on your mobile device, as described in Developing on a Device.
    4. -
  4. If you are using Eclipse, you can view the application log output in Eclipse -using LogCat (Window > Show View > Other > Android > -LogCat).
    5. +
  5. If you are using Android Studio, you can view the application log output by +opening the Event Log console (View > Tool Windows > Event Log). +
  6. Ensure your application is configured to launch Logcat automatically when it runs: +
      +
    1. Select Run > Edit Configurations. +
    2. Select the Miscellaneous tab in the Run/Debug Configurations window. +
    3. Under Logcat, select Show logcat automatically then +select OK.
diff --git a/docs/html/guide/topics/manifest/uses-feature-element.jd b/docs/html/guide/topics/manifest/uses-feature-element.jd old mode 100644 new mode 100755 index 9ac514cb72ac9..1ab10417dce28 --- a/docs/html/guide/topics/manifest/uses-feature-element.jd +++ b/docs/html/guide/topics/manifest/uses-feature-element.jd @@ -486,10 +486,22 @@ determine the features that your application requires.

  1. First, build and export your application as an unsigned .apk. -If you are developing in Eclipse with ADT, right-click the project and select -Android Tools > Export Unsigned Application -Package. Select a destination filename and path and click -OK.
    2. +If you are developing in Android Studio, build your application with Gradle: +
      +
    1. Open the project and select Run > Edit Configurations. +
    2. Select the plus sign near the top-left corner of the Run/Debug +Configurations window. +
    3. Select Gradle. +
    4. Enter Unsigned APK in Name. +
    5. Choose your module from the Gradle project section. +
    6. Enter assemble in Tasks. +
    7. Select OK to complete the new configuration. +
    8. Make sure the Unsigned APK run configuration is selected +in the toolbar and select Run > Run 'Unsigned APK'.
      9. +
    +You can find your unsigned .apk in the +<ProjectName>/app/build/outputs/apk/ directory. +
  2. Next, locate the aapt tool, if it is not already in your PATH. If you are using SDK Tools r8 or higher, you can find aapt in the <SDK>/platform-tools/ directory. @@ -563,9 +575,9 @@ is sensitive to delays or lag in sound input or output. Camera android.hardware.camera The application uses the device's back-facing (main) camera. - Devices with only a front-facing camera do not list this feature, so the - android.hardware.camera.any feature should be - used instead if a camera facing any direction is acceptable for the + Devices with only a front-facing camera do not list this feature, so + the android.hardware.camera.any feature should be used + instead if a camera facing any direction is acceptable for the application. diff --git a/docs/html/guide/topics/providers/content-provider-creating.jd b/docs/html/guide/topics/providers/content-provider-creating.jd old mode 100644 new mode 100755 index 6ec1e1be0244f..7cd3d6998a18c --- a/docs/html/guide/topics/providers/content-provider-creating.jd +++ b/docs/html/guide/topics/providers/content-provider-creating.jd @@ -879,8 +879,8 @@ vnd.android.cursor.item/vnd.com.example.provider.table1 A contract class also helps developers because it usually has mnemonic names for its constants, so developers are less likely to use incorrect values for column names or URIs. Since it's a class, it can contain Javadoc documentation. Integrated development environments such as - Eclipse can auto-complete constant names from the contract class and display Javadoc for the - constants. + Android Studio can auto-complete constant names from the contract class and display Javadoc for + the constants.

    Developers can't access the contract class's class file from your application, but they can diff --git a/docs/html/guide/topics/resources/localization.jd b/docs/html/guide/topics/resources/localization.jd old mode 100644 new mode 100755 index 0a96a1520ba5f..afe4611d54faf --- a/docs/html/guide/topics/resources/localization.jd +++ b/docs/html/guide/topics/resources/localization.jd @@ -1,484 +1,484 @@ -page.title=Localizing with Resources -parent.title=Application Resources -page.tags="localizing","localization","resources", "formats", "l10n" -parent.link=index.html -@jd:body - -

    -
    - -

    Quickview

    - -
      -
    • Use resource sets to create a localized app.
      • -
    • Android loads the correct resource set for the user's language and locale.
      • -
    • If localized resources are not available, Android loads your default resources.
      • -
    - -

    In this document

    -
      -
    1. Overview: Resource-Switching in Android
      2. -
    2. Using Resources for Localization
      3. -
    3. Localization Tips
      4. -
    4. Testing Localized Applications
      5. -
    - -

    See also

    -
      -
    1. Localization Checklist
      2. -
    2. Providing Resources
      3. -
    3. Layouts
      4. -
    4. Activity Lifecycle
      5. -
    -
    -
    - -

    Android will run on many devices in many regions. To reach the most users, -your application should handle text, audio files, numbers, currency, and -graphics in ways appropriate to the locales where your application will be used. -

    - -

    This document describes best practices for localizing Android -applications. The principles apply whether you are developing your application -using ADT with Eclipse, Ant-based tools, or any other IDE.

    - -

    You should already have a working knowledge of Java and be familiar with -Android resource loading, the declaration of user interface elements in XML, -development considerations such as Activity lifecycle, and general principles of -internationalization and localization.

    - -

    It is good practice to use the Android resource framework to separate the -localized aspects of your application as much as possible from the core Java -functionality:

    - - - -

    For a short guide to localizing strings in your app, see the training lesson, Supporting Different Languages.

    - - -

    Overview: Resource-Switching in Android

    - -

    Resources are text strings, layouts, sounds, graphics, and any other static -data that your Android application needs. An application can include multiple -sets of resources, each customized for a different device configuration. When a -user runs the application, Android automatically selects and loads the -resources that best match the device.

    - -

    (This document focuses on localization and locale. For a complete description -of resource-switching and all the types of configurations that you can -specify — screen orientation, touchscreen type, and so on — see Providing -Alternative Resources.)

    - - - - - - - -

    - When you write your application: -

    - You create a set of default resources, plus alternatives to be used in - different locales.

    		 -

    right-arrow

    - When a user runs your application: -

    The Android system selects which resources to load, based on the - device's locale.

    - -

    When you write your application, you create default and alternative resources -for your application to use. To create resources, you place files within -specially named subdirectories of the project's res/ directory. -

    - - - -

    Why Default Resources Are Important

    - -

    Whenever the application runs in a locale for which you have not provided -locale-specific text, Android will load the default strings from -res/values/strings.xml. If this default file is absent, or if it -is missing a string that your application needs, then your application will not run -and will show an error. -The example below illustrates what can happen when the default text file is incomplete.

    - -

    Example: -

    An application's Java code refers to just two strings, text_a and - text_b. This application includes a localized resource file - (res/values-en/strings.xml) that defines text_a and - text_b in English. This application also includes a default - resource file (res/values/strings.xml) that includes a -definition for text_a, but not for text_b: -

    - - -

    To prevent this situation, make sure that a res/values/strings.xml - file exists and that it defines every needed string. The situation applies to - all types of resources, not just strings: You - need to create a set of default resource files containing all - the resources that your application calls upon — layouts, drawables, - animations, etc. For information about testing, see - Testing for Default Resources.

    - -

    Using Resources for Localization

    - -

    How to Create Default Resources

    - -

    Put the application's default text in -a file with the following location and name:

    -

        res/values/strings.xml (required directory)

    - -

    The text strings in res/values/strings.xml should use the -default language, which is the language that you expect most of your application's users to -speak.

    - -

    The default resource set must also include any default drawables and layouts, - and can include other types of resources such as animations. -
    -     res/drawable/(required directory holding at least - one graphic file, for the application's icon on Google Play)
    -     res/layout/ (required directory holding an XML - file that defines the default layout)
    -     res/anim/ (required if you have any - res/anim-<qualifiers> folders)
    -     res/xml/ (required if you have any - res/xml-<qualifiers> folders)
    -     res/raw/ (required if you have any - res/raw-<qualifiers> folders) -

    - -

    Tip: In your code, examine each reference to - an Android resource. Make sure that a default resource is defined for each - one. Also make sure that the default string file is complete: A - localized string file can contain a subset of the strings, but the - default string file must contain them all. -

    - -

    How to Create Alternative Resources

    - -

    A large part of localizing an application is providing alternative text for -different languages. In some cases you will also provide alternative graphics, -sounds, layouts, and other locale-specific resources.

    - -

    An application can specify many res/<qualifiers>/ -directories, each with different qualifiers. To create an alternative resource for -a different locale, you use a qualifier that specifies a language or a -language-region combination. (The name of a resource directory must conform -to the naming scheme described in -Providing -Alternative Resources, -or else it will not compile.)

    - -

    Example:

    - -

    Suppose that your application's default language is English. Suppose also -that you want to localize all the text in your application to French, and most -of the text in your application (everything except the application's title) to -Japanese. In this case, you could create three alternative strings.xml -files, each stored in a locale-specific resource directory:

    - -
      -
    1. res/values/strings.xml
      - Contains English text for all the strings that the application uses, -including text for a string named title.
      2. -
    2. res/values-fr/strings.xml
      - Contain French text for all the strings, including title.
      3. -
    3. res/values-ja/strings.xml
      - Contain Japanese text for all the strings except -title.
      -
      4. -
    - -

    If your Java code refers to R.string.title, here is what will -happen at runtime:

    - - - -

    Notice that if the device is set to Japanese, Android will look for -title in the res/values-ja/strings.xml file. But -because no such string is included in that file, Android will fall back to the -default, and will load title in English from the -res/values/strings.xml file.

    - -

    Which Resources Take Precedence?

    - -

    If multiple resource files match a device's configuration, Android follows a -set of rules in deciding which file to use. Among the qualifiers that can be -specified in a resource directory name, locale almost always takes -precedence.

    -

    Example:

    - -

    Assume that an application includes a default set of graphics and two other -sets of graphics, each optimized for a different device setup:

    - - - -

    If the application runs on a device that is configured to use Japanese, -Android will load graphics from res/drawable-ja/, even if the -device happens to be one that expects input from a stylus and has a QVGA -low-density screen in landscape orientation.

    - -

    Exception: The only qualifiers that take -precedence over locale in the selection process are MCC and MNC (mobile country -code and mobile network code).

    - -

    Example:

    - -

    Assume that you have the following situation:

    - - - -

    Android will load text_a from -res/values-mcc404/strings.xml (in English), even if the device is -configured for Hindi. That is because in the resource-selection process, Android -will prefer an MCC match over a language match.

    - -

    The selection process is not always as straightforward as these examples -suggest. Please read How Android Finds -the Best-matching Resource for a more nuanced description of the -process. All the qualifiers are described and listed in order of -precedence in Table 2 of Providing -Alternative Resources.

    - -

    Referring to Resources in Java

    - -

    In your application's Java code, you refer to resources using the syntax -R.resource_type.resource_name or -android.R.resource_type.resource_name. -For more about this, see Accessing Resources.

    - -

    Localization Checklist

    - -

    For a complete overview of the process of localizing and distributing an Android application, -see the Localization -Checklist document.

    - -

    Localization Tips

    - -

    Design your application to work in any locale

    - -

    You cannot assume anything about the device on which a user will -run your application. The device might have hardware that you were not -anticipating, or it might be set to a locale that you did not plan for or that -you cannot test. Design your application so that it will function normally or fail gracefully no -matter what device it runs on.

    - -

    Important: Make sure that your application -includes a full set of default resources.

    Make sure to include -res/drawable/ and a res/values/ folders (without any -additional modifiers in the folder names) that contain all the images and text -that your application will need.

    - -

    If an application is missing even one default resource, it will not run on a - device that is set to an unsupported locale. For example, the - res/values/strings.xml default file might lack one string that - the application needs: When the application runs in an unsupported locale and - attempts to load res/values/strings.xml, the user will see an - error message and a Force Close button. An IDE such as Eclipse will not - highlight this kind of error, and you will not see the problem when you - test the application on a device or emulator that is set to a supported locale.

    - -

    For more information, see Testing for Default Resources.

    - -

    Design a flexible layout

    - -

    If you need to rearrange your layout to fit a certain language (for example -German with its long words), you can create an alternative layout for that -language (for example res/layout-de/main.xml). However, doing this -can make your application harder to maintain. It is better to create a single -layout that is more flexible.

    - -

    Another typical situation is a language that requires something different in -its layout. For example, you might have a contact form that should include two -name fields when the application runs in Japanese, but three name fields when -the application runs in some other language. You could handle this in either of -two ways:

    - - - -

    Avoid creating more resource files and text strings than you need

    - -

    You probably do not need to create a locale-specific -alternative for every resource in your application. For example, the layout -defined in the res/layout/main.xml file might work in any locale, -in which case there would be no need to create any alternative layout files. -

    - -

    Also, you might not need to create alternative text for every -string. For example, assume the following:

    - - - -

    To do this, you could create a small file called -res/values-en-rGB/strings.xml that includes only the strings that -should be different when the application runs in the U.K. For all the rest of -the strings, the application will fall back to the defaults and use what is -defined in res/values/strings.xml.

    - -

    Use the Android Context object for manual locale lookup

    - -

    You can look up the locale using the {@link android.content.Context} object -that Android makes available:

    - -
    String locale = context.getResources().getConfiguration().locale.getDisplayName();
    - -

    Testing Localized Applications

    - -

    Testing on a Device

    -

    Keep in mind that the device you are testing may be significantly different from - the devices available to consumers in other geographies. The locales available - on your device may differ from those available on other devices. Also, the - resolution and density of the device screen may differ, which could affect - the display of strings and drawables in your UI.

    - -

    To change the locale or language on a device, use the Settings application.

    - -

    Testing on an Emulator

    - -

    For details about using the emulator, see See Android Emulator.

    -

    Creating and using a custom locale

    - -

    A "custom" locale is a language/region combination that the Android -system image does not explicitly support. (For a list of supported locales in -Android platforms see the Version Notes in the SDK tab). You can test -how your application will run in a custom locale by creating a custom locale in -the emulator. There are two ways to do this:

    - - - -

    When you set the emulator to a locale that is not available in the Android -system image, the system itself will display in its default language. Your -application, however, should localize properly.

    - -

    Changing the emulator locale from the adb shell

    - -

    To change the locale in the emulator by using the adb shell.

    - -
      -
    1. Pick the locale you want to test and determine its BCP-47 language tag, for -example, Canadian French would be fr-CA.
      -
      2. -
    2. Launch an emulator.
      3. -
    3. From a command-line shell on the host computer, run the following -command:
      - adb shell
      - or if you have a device attached, specify that you want the emulator by adding -the -e option:
      - adb -e shell
      4. -
    4. At the adb shell prompt (#), run this command:
      - setprop persist.sys.locale [BCP-47 language tag];stop;sleep 5;start
      -       Replace bracketed sections with the appropriate codes from Step -1.
      5. -
    - -

    For instance, to test in Canadian French:

    - -

    setprop persist.sys.locale fr-CA;stop;sleep 5;start

    - -

    This will cause the emulator to restart. (It will look like a full reboot, -but it is not.) Once the Home screen appears again, re-launch your application (for -example, click the Run icon in Eclipse), and the application will launch with -the new locale.

    - -

    Testing for Default Resources

    -

    Here's how to test whether an application includes every string resource that it needs:

    -
    1. Set the emulator or device to a language that your application does not - support. For example, if the application has French strings in - res/values-fr/ but does not have any Spanish strings in - res/values-es/, then set the emulator's locale to Spanish. - (You can use the Custom Locale application to set the emulator to an - unsupported locale.)
      2. -
    2. Run the application.
      3. -
    3. If the application shows an error message and a Force Close button, it might - be looking for a string that is not available. Make sure that your - res/values/strings.xml file includes a definition for - every string that the application uses.
      4. -
    -

    - -

    If the test is successful, repeat it for other types of - configurations. For example, if the application has a layout file called - res/layout-land/main.xml but does not contain a file called - res/layout-port/main.xml, then set the emulator or device to - portrait orientation and see if the application will run. - - - +page.title=Localizing with Resources +parent.title=Application Resources +page.tags="localizing","localization","resources", "formats", "l10n" +parent.link=index.html +@jd:body + +

    +
    + +

    Quickview

    + +
      +
    • Use resource sets to create a localized app.
      • +
    • Android loads the correct resource set for the user's language and locale.
      • +
    • If localized resources are not available, Android loads your default resources.
      • +
    + +

    In this document

    +
      +
    1. Overview: Resource-Switching in Android
      2. +
    2. Using Resources for Localization
      3. +
    3. Localization Tips
      4. +
    4. Testing Localized Applications
      5. +
    + +

    See also

    +
      +
    1. +Localization Checklist
      2. +
    2. +Providing Resources
      3. +
    3. +Layouts
      4. +
    4. +Activity Lifecycle
      5. +
    +
    +
    + +

    Android will run on many devices in many regions. To reach the most users, +your application should handle text, audio files, numbers, currency, and +graphics in ways appropriate to the locales where your application will be used. +

    + +

    This document describes best practices for localizing Android +applications.

    + +

    You should already have a working knowledge of Java and be familiar with +Android resource loading, the declaration of user interface elements in XML, +development considerations such as Activity lifecycle, and general principles of +internationalization and localization.

    + +

    It is good practice to use the Android resource framework to separate the +localized aspects of your application as much as possible from the core Java +functionality:

    + + + +

    For a short guide to localizing strings in your app, see the training lesson, + +Supporting Different Languages.

    + + +

    Overview: Resource-Switching in Android

    + +

    Resources are text strings, layouts, sounds, graphics, and any other static +data that your Android application needs. An application can include multiple +sets of resources, each customized for a different device configuration. When a +user runs the application, Android automatically selects and loads the +resources that best match the device.

    + +

    (This document focuses on localization and locale. For a complete description +of resource-switching and all the types of configurations that you can +specify — screen orientation, touchscreen type, and so on — +see +Providing Alternative Resources.)

    + + + + + + + +

    +When you write your application: +

    +You create a set of default resources, plus alternatives to be used in +different locales.

    		 +

    +right-arrow

    + When a user runs your application: +

    The Android system selects which resources to load, based on the + device's locale.

    + +

    When you write your application, you create default and alternative resources +for your application to use. To create resources, you place files within +specially named subdirectories of the project's res/ directory. +

    + + + +

    Why Default Resources Are Important

    + +

    Whenever the application runs in a locale for which you have not provided +locale-specific text, Android will load the default strings from +res/values/strings.xml. If this default file is absent, or if it +is missing a string that your application needs, then your application will not run +and will show an error. +The example below illustrates what can happen when the default text file is +incomplete.

    + +

    Example: +

    An application's Java code refers to just two strings, text_a and + text_b. This application includes a localized resource file + (res/values-en/strings.xml) that defines text_a and + text_b in English. This application also includes a default + resource file (res/values/strings.xml) that includes a +definition for text_a, but not for text_b: +

    + + +

    To prevent this situation, make sure that a res/values/strings.xml + file exists and that it defines every needed string. The situation applies to + all types of resources, not just strings: You + need to create a set of default resource files containing all + the resources that your application calls upon — layouts, drawables, + animations, etc. For information about testing, see + Testing for Default Resources.

    + +

    Using Resources for Localization

    + +

    How to Create Default Resources

    + +

    Put the application's default text in +a file with the following location and name:

    +

        res/values/strings.xml (required directory)

    + +

    The text strings in res/values/strings.xml should use the +default language, which is the language that you expect most of your application's users to +speak.

    + +

    The default resource set must also include any default drawables and layouts, + and can include other types of resources such as animations. +
    +     res/drawable/(required directory holding at least + one graphic file, for the application's icon on Google Play)
    +     res/layout/ (required directory holding an XML + file that defines the default layout)
    +     res/anim/ (required if you have any + res/anim-<qualifiers> folders)
    +     res/xml/ (required if you have any + res/xml-<qualifiers> folders)
    +     res/raw/ (required if you have any + res/raw-<qualifiers> folders) +

    + +

    Tip: In your code, examine each reference to + an Android resource. Make sure that a default resource is defined for each + one. Also make sure that the default string file is complete: A + localized string file can contain a subset of the strings, but the + default string file must contain them all. +

    + +

    How to Create Alternative Resources

    + +

    A large part of localizing an application is providing alternative text for +different languages. In some cases you will also provide alternative graphics, +sounds, layouts, and other locale-specific resources.

    + +

    An application can specify many res/<qualifiers>/ +directories, each with different qualifiers. To create an alternative resource for +a different locale, you use a qualifier that specifies a language or a +language-region combination. (The name of a resource directory must conform +to the naming scheme described in +Providing +Alternative Resources, +or else it will not compile.)

    + +

    Example:

    + +

    Suppose that your application's default language is English. Suppose also +that you want to localize all the text in your application to French, and most +of the text in your application (everything except the application's title) to +Japanese. In this case, you could create three alternative strings.xml +files, each stored in a locale-specific resource directory:

    + +
      +
    1. res/values/strings.xml
      + Contains English text for all the strings that the application uses, +including text for a string named title.
      2. +
    2. res/values-fr/strings.xml
      + Contain French text for all the strings, including title.
      3. +
    3. res/values-ja/strings.xml
      + Contain Japanese text for all the strings except +title.
      +
      4. +
    + +

    If your Java code refers to R.string.title, here is what will +happen at runtime:

    + + + +

    Notice that if the device is set to Japanese, Android will look for +title in the res/values-ja/strings.xml file. But +because no such string is included in that file, Android will fall back to the +default, and will load title in English from the +res/values/strings.xml file.

    + +

    Which Resources Take Precedence?

    + +

    If multiple resource files match a device's configuration, Android follows a +set of rules in deciding which file to use. Among the qualifiers that can be +specified in a resource directory name, locale almost always takes +precedence.

    +

    Example:

    + +

    Assume that an application includes a default set of graphics and two other +sets of graphics, each optimized for a different device setup:

    + + + +

    If the application runs on a device that is configured to use Japanese, +Android will load graphics from res/drawable-ja/, even if the +device happens to be one that expects input from a stylus and has a QVGA +low-density screen in landscape orientation.

    + +

    Exception: The only qualifiers that take +precedence over locale in the selection process are MCC and MNC (mobile country +code and mobile network code).

    + +

    Example:

    + +

    Assume that you have the following situation:

    + + + +

    Android will load text_a from +res/values-mcc404/strings.xml (in English), even if the device is +configured for Hindi. That is because in the resource-selection process, Android +will prefer an MCC match over a language match.

    + +

    The selection process is not always as straightforward as these examples +suggest. Please read How Android Finds +the Best-matching Resource for a more nuanced description of the +process. All the qualifiers are described and listed in order of +precedence in Table 2 of Providing +Alternative Resources.

    + +

    Referring to Resources in Java

    + +

    In your application's Java code, you refer to resources using the syntax +R.resource_type.resource_name or +android.R.resource_type.resource_name. +For more about this, see Accessing Resources.

    + +

    Localization Checklist

    + +

    For a complete overview of the process of localizing and distributing an Android application, +see the Localization +Checklist document.

    + +

    Localization Tips

    + +

    Design your application to work in any locale

    + +

    You cannot assume anything about the device on which a user will +run your application. The device might have hardware that you were not +anticipating, or it might be set to a locale that you did not plan for or that +you cannot test. Design your application so that it will function normally or fail gracefully no +matter what device it runs on.

    + +

    Important: Make sure that your application +includes a full set of default resources.

    Make sure to include +res/drawable/ and a res/values/ folders (without any +additional modifiers in the folder names) that contain all the images and text +that your application will need.

    + +

    If an application is missing even one default resource, it will not run on a +device that is set to an unsupported locale. For example, the +res/values/strings.xml default file might lack one string that +the application needs: When the application runs in an unsupported locale and +attempts to load res/values/strings.xml, the user will see an +error message and a Force Close button.

    + +

    For more information, see Testing for Default Resources.

    + +

    Design a flexible layout

    + +

    If you need to rearrange your layout to fit a certain language (for example +German with its long words), you can create an alternative layout for that +language (for example res/layout-de/main.xml). However, doing this +can make your application harder to maintain. It is better to create a single +layout that is more flexible.

    + +

    Another typical situation is a language that requires something different in +its layout. For example, you might have a contact form that should include two +name fields when the application runs in Japanese, but three name fields when +the application runs in some other language. You could handle this in either of +two ways:

    + + + +

    Avoid creating more resource files and text strings than you need

    + +

    You probably do not need to create a locale-specific +alternative for every resource in your application. For example, the layout +defined in the res/layout/main.xml file might work in any locale, +in which case there would be no need to create any alternative layout files. +

    + +

    Also, you might not need to create alternative text for every +string. For example, assume the following:

    + + + +

    To do this, you could create a small file called +res/values-en-rGB/strings.xml that includes only the strings that +should be different when the application runs in the U.K. For all the rest of +the strings, the application will fall back to the defaults and use what is +defined in res/values/strings.xml.

    + +

    Use the Android Context object for manual locale lookup

    + +

    You can look up the locale using the {@link android.content.Context} object +that Android makes available:

    + +
    String locale = context.getResources().getConfiguration().locale.getDisplayName();
    + +

    Testing Localized Applications

    + +

    Testing on a Device

    +

    Keep in mind that the device you are testing may be significantly different from + the devices available to consumers in other geographies. The locales available + on your device may differ from those available on other devices. Also, the + resolution and density of the device screen may differ, which could affect + the display of strings and drawables in your UI.

    + +

    To change the locale or language on a device, use the Settings application.

    + +

    Testing on an Emulator

    + +

    For details about using the emulator, see See Android Emulator.

    +

    Creating and using a custom locale

    + +

    A "custom" locale is a language/region combination that the Android +system image does not explicitly support. (For a list of supported locales in +Android platforms see the Version Notes in the SDK tab). You can test +how your application will run in a custom locale by creating a custom locale in +the emulator. There are two ways to do this:

    + + + +

    When you set the emulator to a locale that is not available in the Android +system image, the system itself will display in its default language. Your +application, however, should localize properly.

    + +

    Changing the emulator locale from the adb shell

    + +

    To change the locale in the emulator by using the adb shell.

    + +
      +
    1. Pick the locale you want to test and determine its BCP-47 language tag, for +example, Canadian French would be fr-CA.
      +
      2. +
    2. Launch an emulator.
      3. +
    3. From a command-line shell on the host computer, run the following +command:
      + adb shell
      + or if you have a device attached, specify that you want the emulator by adding +the -e option:
      + adb -e shell
      4. +
    4. At the adb shell prompt (#), run this command:
      + setprop persist.sys.locale [BCP-47 language tag];stop;sleep 5;start
      +       Replace bracketed sections with the appropriate codes from Step +1.
      5. +
    + +

    For instance, to test in Canadian French:

    + +

    setprop persist.sys.locale fr-CA;stop;sleep 5;start

    + +

    This will cause the emulator to restart. (It will look like a full reboot, +but it is not.) Once the Home screen appears again, re-launch your application, + and the application launches with the new locale.

    + +

    Testing for Default Resources

    +

    Here's how to test whether an application includes every string +resource that it needs:

    +
    1. Set the emulator or device to a language that your application does not +support. For example, if the application has French strings in +res/values-fr/ but does not have any Spanish strings in +res/values-es/, then set the emulator's locale to Spanish. +(You can use the Custom Locale application to set the emulator to an +unsupported locale.)
      2. +
    2. Run the application.
      3. +
    3. If the application shows an error message and a Force Close button, it might +be looking for a string that is not available. Make sure that your +res/values/strings.xml file includes a definition for +every string that the application uses.
      4. +
    +

    + +

    If the test is successful, repeat it for other types of +configurations. For example, if the application has a layout file called +res/layout-land/main.xml but does not contain a file called +res/layout-port/main.xml, then set the emulator or device to +portrait orientation and see if the application will run. diff --git a/docs/html/ndk/guides/concepts.jd b/docs/html/ndk/guides/concepts.jd old mode 100644 new mode 100755 index 0601f212e2301..c56143ff2caa4 --- a/docs/html/ndk/guides/concepts.jd +++ b/docs/html/ndk/guides/concepts.jd @@ -18,12 +18,9 @@ page.title=Concepts

    Before Beginning

    -

    This guide assumes that you are:

    -

    Introduction

    @@ -151,15 +148,13 @@ native code.

    Note: While it is possible to completely avoid Java, you are likely to find the Android Java framework useful for tasks including controlling the display and UI.

    3. - -
  3. Create an Android app Project in Eclipse as you would for any other Android project.
    4. +
  4. Create an Android app Project as you would for any other Android project.
  5. If you are writing a native-only app, declare the {@link android.app.NativeActivity} class in -{@code AndroidManifest.xml}. You can do so from the Eclipse/ADT Android Manifest Editor, or by -hand-editing the file. For more information, see the Native Activities and +{@code AndroidManifest.xml}. For more information, see the Native Activities and Applications.
  6. Create an {@code Android.mk} file describing the native library, including name, flags, linked -libraries, and source files to be compiled in the ‘JNI’ directory.
    7. +libraries, and source files to be compiled in the "JNI" directory.
  7. Optionally, you can create an {@code Application.mk} file configuring the target ABIs, toolchain, release/debug mode, and STL. For any of these that you do not specify, the following default values are used, respectively: @@ -184,7 +179,6 @@ STL: system needed for your app to run.
-

Note that Eclipse can perform steps 7. through 9. in a single operation.

Native Activities and Applications

@@ -300,7 +294,7 @@ $ cd <path>/<to>/<project> $ <ndk>/ndk-build -
  • Build and install your Android project as usual, using Ant or Eclipse. If your native code is in +
  • Build and install your Android project as usual. If your native code is in the {@code jni/} directory, the build script automatically packages the {@code .so} file(s) built from it into the APK.
    • diff --git a/docs/html/ndk/guides/standalone_toolchain.jd b/docs/html/ndk/guides/standalone_toolchain.jd old mode 100644 new mode 100755 index 3b6f7f1ceb4ec..e08d531ec7306 --- a/docs/html/ndk/guides/standalone_toolchain.jd +++ b/docs/html/ndk/guides/standalone_toolchain.jd @@ -17,7 +17,7 @@ page.title=Standalone Toolchain

    You can use the toolchains provided with the Android NDK independently, or as plug-ins -with an existing IDE, such as Eclipse. This flexibility +with an existing IDE. This flexibility can be useful if you already have your own build system, and only need the ability to invoke the cross-compiler in order to add support to Android for it.

    diff --git a/docs/html/tools/help/gltracer.jd b/docs/html/tools/help/gltracer.jd old mode 100644 new mode 100755 index 700ee39c5766e..866bdc93578d2 --- a/docs/html/tools/help/gltracer.jd +++ b/docs/html/tools/help/gltracer.jd @@ -26,17 +26,6 @@ Level 16) or higher.

    Running Tracer

    -

    Tracer can be run as part of the Eclipse Android Development Tools (ADT) plugin or as part of the -Device Monitor tool.

    - -

    To run Tracer in Eclipse:

    - -
      -
    1. Start Eclipse and open a workspace that contains an Android project.
      2. -
    2. Activate the perspective for Tracer by choosing Window > Open Perspective > -Other...
      3. -
    3. Select Tracer for OpenGL ES and click OK.
      4. -

    To run Tracer in Device Monitor:

    @@ -64,7 +53,7 @@ analysis.

    1. Connect the Android device using a USB cable and make sure it is enabled for debugging. For more information, see Using Hardware Devices.
      2. -
    2. In Eclipse or Device Monitor, activate the Tracer for OpenGL ES +
    3. In the Device Monitor, activate the Tracer for OpenGL ES perspective.
    4. On the toolbar, click the trace capture button ().
      5. @@ -94,10 +83,10 @@ Be aware that using this option can result in large trace files.

      To review a captured trace:

        -
      1. In Eclipse or Device Monitor, activate the Tracer for OpenGL ES +
      2. In Device Monitor, activate the Tracer for OpenGL ES perspective.
      3. On the toolbar, click the trace load button ().
      4. After loading a trace, select a frame and review the OpenGL ES calls. Drawing commands are highlighted in blue.
        5. -
      \ No newline at end of file +
    diff --git a/docs/html/tools/help/proguard.jd b/docs/html/tools/help/proguard.jd old mode 100644 new mode 100755 index b5d84ed852597..5482399522eca --- a/docs/html/tools/help/proguard.jd +++ b/docs/html/tools/help/proguard.jd @@ -117,76 +117,6 @@ parent.link=index.html - -

    Enabling ProGuard (Ant Builds)

    - -

    When you create an Android project, a proguard.cfg file is automatically - generated in the root directory of the project. This file defines how ProGuard optimizes and - obfuscates your code, so it is very important that you understand how to customize it for your - needs. The default configuration file only covers general cases, so you most likely have to edit - it for your own needs. See the following section about Configuring - ProGuard for information on customizing the ProGuard configuration file.

    - -

    To enable ProGuard so that it runs as part of an Ant or Eclipse build, set the - proguard.config property in the <project_root>/project.properties - file. The path can be an absolute path or a path relative to the project's root.

    - -

    If you left the proguard.cfg file in its default location (the project's root - directory), you can specify its location like this:

    - -
    -proguard.config=proguard.cfg
-
    - -

    -You can also move the the file to anywhere you want, and specify the absolute path to it: -

    - -
    -proguard.config=/path/to/proguard.cfg
-
    - -

    When you build your application in release mode, either by running ant release or - by using the Export Wizard in Eclipse, the build system automatically checks to see if - the proguard.config property is set. If it is, ProGuard automatically processes - the application's bytecode before packaging everything into an .apk file. Building in debug mode - does not invoke ProGuard, because it makes debugging more cumbersome.

    - -

    ProGuard outputs the following files after it runs:

    - -
    -
    dump.txt
    -
    Describes the internal structure of all the class files in the .apk file
    - -
    mapping.txt
    -
    Lists the mapping between the original and obfuscated class, method, and field names. - This file is important when you receive a bug report from a release build, because it - translates the obfuscated stack trace back to the original class, method, and member names. - See Decoding Obfuscated Stack Traces for more information.
    - -
    seeds.txt
    -
    Lists the classes and members that are not obfuscated
    - -
    usage.txt
    -
    Lists the code that was stripped from the .apk
    - - -

    These files are located in the following directories:

    - - - - -

    Caution: Every time you run a build in release mode, these files are - overwritten with the latest files generated by ProGuard. Save a copy of them each time you release your - application in order to de-obfuscate bug reports from your release builds. - For more information on why saving these files is important, see - Debugging considerations for published applications. -

    -

    Configuring ProGuard

    For some situations, the default configurations in the ProGuard configuration file will @@ -246,9 +176,7 @@ proguard.config=/path/to/proguard.cfg By retaining a copy of the mapping.txt file for each release build, you ensure that you can debug a problem if a user encounters a bug and submits an obfuscated stack trace. A project's mapping.txt file is overwritten every time you do a release build, so you must be - careful about saving the versions that you need. For Eclipse, this file is stored in - <project_root>/bin/proguard/. For Android Studio, this file is stored in - the app build/outs/ folder.

    + careful about saving the versions that you need. The file is stored in the app build/outs/ folder.

    For example, say you publish an application and continue developing new features of the application for a new version. You then do a release build using ProGuard soon after. The