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
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.