Bug 917480 - Developer docs for Fennec locale switching. DONTBUILD, r=doc-only
authorRichard Newman <rnewman@mozilla.com>
Mon, 30 Jun 2014 15:22:48 -0700
changeset 191654 582caed4aacf
parent 191653 8241767aa510
child 191655 a031c620067b
push id27056
push usercbook@mozilla.com
push date2014-07-01 12:22 +0000
treeherdermozilla-central@f207bcb19c2d [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersdoc-only
bugs917480
milestone33.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 917480 - Developer docs for Fennec locale switching. DONTBUILD, r=doc-only
mobile/android/base/BrowserLocaleManager.java
mobile/android/base/docs/localeswitching.rst
--- a/mobile/android/base/BrowserLocaleManager.java
+++ b/mobile/android/base/BrowserLocaleManager.java
@@ -200,17 +200,17 @@ public class BrowserLocaleManager implem
      * thing we care about, and we actively correct incoming configuration
      * changes to reflect the user's chosen locale.
      *
      * By contrast, when we are mirroring, system locale changes cause Firefox
      * to reflect the new system locale, as if the user picked the new locale.
      *
      * If we're currently mirroring the system locale, this method returns the
      * supplied configuration's locale, unless the current activity locale is
-     * correct. , If we're not currently mirroring, this methodupdates the
+     * correct. If we're not currently mirroring, this method updates the
      * configuration object to match the user's currently selected locale, and
      * returns that, unless the current activity locale is correct.
      *
      * If the current activity locale is correct, returns null.
      *
      * The caller is expected to redisplay themselves accordingly.
      *
      * This method is intended to be called from inside
new file mode 100644
--- /dev/null
+++ b/mobile/android/base/docs/localeswitching.rst
@@ -0,0 +1,95 @@
+==================================
+Runtime locale switching in Fennec
+==================================
+
+`Bug 917480 <https://bugzilla.mozilla.org/show_bug.cgi?id=917480>`_ built on `Bug 936756 <https://bugzilla.mozilla.org/show_bug.cgi?id=936756>`_ to allow users to switch between supported locales at runtime, within Fennec, without altering the system locale.
+
+This document aims to describe the overall architecture of the solution, along with guidelines for Fennec developers.
+
+Overview
+========
+
+There are two places that locales are relevant to an Android application: the Java ``Locale`` object and the Android configuration itself.
+
+Locale switching involves manipulating these values (to affect future UI), persisting them for future activities, and selectively redisplaying existing UI elements to give the appearance of responsive switching.
+
+The user's choice of locale is stored in a per-app pref, ``"locale"``. If missing, the system default locale is used. If set, it should be a locale code like ``"es"`` or ``"en-US"``.
+
+``BrowserLocaleManager`` takes care of updating the active locale when asked to do so. It also manages persistence and retrieval of the locale preference.
+
+The question, then, is when to do so.
+
+Locale events
+=============
+
+One might imagine that we need only set the locale when our Application is instantiated, and when a new locale is set. Alas, that's not the case: whenever there's a configuration change (*e.g.*, screen rotation), when a new activity is started, and at other apparently random times, Android will supply our activities with a configuration that's been reset to the sytem locale.
+
+For this reason, each starting activity must ask ``BrowserLocaleManager`` to fix its locale.
+
+Ideally, we also need to perform some amount of work when our configuration changes, when our activity is resumed, and perhaps when a result is returned from another activity, if that activity can change the app locale (as is the case for any activity that calls out to ``GeckoPreferences`` -- see ``BrowserApp#onActivityResult``).
+
+``GeckoApp`` itself does some additional work, because it has particular performance constraints, and also is the typical root of the preferences activity.
+
+Here's an example of the work that a typical activity should do::
+
+  // This is cribbed from o.m.g.sync.setup.activities.LocaleAware.
+  public static void initializeLocale(Context context) {
+    final LocaleManager localeManager = BrowserLocaleManager.getInstance();
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.GINGERBREAD) {
+      localeManager.getAndApplyPersistedLocale(context);
+    } else {
+      final StrictMode.ThreadPolicy savedPolicy = StrictMode.allowThreadDiskReads();
+      StrictMode.allowThreadDiskWrites();
+      try {
+        localeManager.getAndApplyPersistedLocale(context);
+      } finally {
+        StrictMode.setThreadPolicy(savedPolicy);
+      }
+    }
+  }
+
+  @Override
+  public void onConfigurationChanged(Configuration newConfig) {
+    final LocaleManager localeManager = BrowserLocaleManager.getInstance();
+    final Locale changed = localeManager.onSystemConfigurationChanged(this, getResources(), newConfig, mLastLocale);
+    if (changed != null) {
+      // Redisplay to match the locale.
+      onLocaleChanged(BrowserLocaleManager.getLanguageTag(changed));
+    }
+  }
+
+  @Override
+  public void onCreate(Bundle icicle) {
+    // Note that we don't do this in onResume. We should,
+    // but it's an edge case that we feel free to ignore.
+    // We also don't have a hook in this example for when
+    // the user picks a new locale.
+    initializeLocale(this);
+
+    super.onCreate(icicle);
+  }
+
+``GeckoApplication`` itself handles correcting locales when the configuration changes; your activity shouldn't need to do this itself. See ``GeckoApplication``'s and ``GeckoApp``'s ``onConfigurationChanged`` methods.
+
+System locale changes
+=====================
+
+Fennec can be in one of two states.
+
+If the user has not explicitly chosen a Fennec-specific locale, we say
+we are "mirroring" the system locale.
+
+When we are not mirroring, system locale changes do not impact Fennec
+and are essentially ignored; the user's locale selection is the only
+thing we care about, and we actively correct incoming configuration
+changes to reflect the user's chosen locale.
+
+By contrast, when we are mirroring, system locale changes cause Fennec
+to reflect the new system locale, as if the user picked the new locale.
+
+When the system locale changes when we're mirroring, your activity will receive an ``onConfigurationChanged`` call. Simply pass this on to ``BrowserLocaleManager``, and then handle the response appropriately.
+
+Further reference
+=================
+
+``GeckoPreferences``, ``GeckoApp``, and ``BrowserApp`` are excellent resources for figuring out what you should do.