languagesPrivate IDL draft

chrome/common/extensions/api/languages_private.idl

Index: chrome/common/extensions/api/languages_private.idl
diff --git a/chrome/common/extensions/api/languages_private.idl b/chrome/common/extensions/api/languages_private.idl
new file mode 100644
index 0000000000000000000000000000000000000000..9b586ec33c5b03540cb03a78850e9d292d75ef53
--- /dev/null
+++ b/chrome/common/extensions/api/languages_private.idl
@@ -0,0 +1,119 @@
+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// Use the <code>chrome.languagesPrivate</code> API to get or change language and
+// input method settings.
+namespace languagesPrivate {
+  // Status of a spell check dictionary download.
+  enum DownloadStatus { DOWNLOADED, DOWNLOADING, FAILURE };
+
+  dictionary Language {
+    DOMString code;
+    DOMString displayName;
+    DOMString nativeDisplayName;
+    boolean rtl;
+    boolean supportsSpellCheck;
+    boolean supportsTranslate;

[not at google - send to devlin, 2015/04/24 16:53:43]

consider making the booleans optional (and default-false; reword them if the
common case is for them to be true, i.e. "disableSpellCheck" and
"disableTranslate" if appropriate) so that you don't need to shuffle around
redundant data.

[michaelpg, 2015/05/09 01:12:29]

Done.

+  };
+
+  dictionary LanguagesInfo {
+    // All languages available for translate, spell checking, input and locale.
+    Language[] languages;
+
+    // The language code for the current locale setting.
+    DOMString currentLocale;

[stevenjb, 2015/04/24 00:00:20]

Does this match 'Language.code'? If so, maybe we should name them the same, i.e.
s/code/locale above?

[not at google - send to devlin, 2015/04/24 16:53:43]

Is this something a web API can give you anyway? like navigator.language or
whatever?

[michaelpg, 2015/05/09 01:12:29]

I'll standardize this better.

Technically a locale can be described with a combination of language code,
[country code], [variant code] and [maybe other stuff].

There is a one-to-many relationship between a language and its associated
locales, so really just about everything in this API should be called a locale.

But locale can also refer to how to format dates, 

Chrome UI tends to use "locale" to mean "display locale", as opposed to
translate/spell check locales.

[michaelpg, 2015/05/09 01:12:29]

navigator.language corresponds to the value of intl.app_locale from startup. We
want the value of intl.app_locale as it is currently set -- the user may change
the display language but not restart immediately.

I can move this to settingsPrivate though since it's just a basic setting.

+
+    // The language codes that can be used for the locale.
+    DOMString[] availableLocales;
+
+    // The language to translate to.
+    DOMString translateTargetLanguage;
+
+    // The language used for spell checking.
+    DOMString spellCheckLanguage;

[not at google - send to devlin, 2015/04/24 16:53:42]

What does translate/spellcheck data have to do with "LanguagesInfo" struct?
"supports", sure, but the actual language?

[michaelpg, 2015/05/09 01:12:29]

LanguagesInfo was a confusing construct. Removed.

+
+    // Whether spell check auto-correct is enabled.
+    boolean autoCorrectEnabled;

[not at google - send to devlin, 2015/04/24 16:53:43]

Ditto(s)

[michaelpg, 2015/05/09 01:12:29]

Acknowledged.

+  };
+
+  dictionary SpellCheckDictionaryStatus {
+    // The language of the dictionary.
+    DOMString languageCode;

[stevenjb, 2015/04/24 00:00:20]

Same as Language.code? or currentLocale? or different?

[michaelpg, 2015/04/24 19:08:03]

No, you can use any language for spell checking. So this is not the same as
currentLocale. Yes, it would be the value of the ".code" for some Language.

+
+    // The downloading status.
+    DownloadStatus status;
+  };
+
+  dictionary InputMethod {
+    // The ID of the input method descriptor.
+    DOMString id;
+
+    // The human-readable name of the input method.
+    DOMString displayName;
+
+    // The name of the extension providing the input method, if any.
+    DOMString? extensionName;

[not at google - send to devlin, 2015/04/24 16:53:43]

You will probably want to fetch other things, like the icon, so it would be
better composed if you were to send down an ID then use another API (like
chrome.management) to fetch the relevant data about it.

Or, just plan to add the icon to this field I suppose. That would save some JS
code, but not compose as well.

Also: what language will the extension name be?

[michaelpg, 2015/05/09 01:12:29]

You're right, we can just use the ID with chrome.management for the name, icon,
options URL, etc.

+
+    // The URL for the options page for the extension, if any.
+    DOMString? optionsPage;
+
+    // The language codes this input method supports.
+    DOMString[] languages;

[stevenjb, 2015/04/24 00:00:20]

code? locale?

+
+    // True if the input method is enabled.
+    boolean enabled;
+  };
+
+  dictionary InputMethodsInfo {
+    // The list of built-in input methods.
+    InputMethod[] inputMethods;
+    
+    // The list of component extension input methods.
+    InputMethod[] componentExtensionIMEs;
+
+    // The list of third-party extension input methods.
+    InputMethod[] thirdPartyExtensionIMEs;
+  };
+
+  callback GetLanguagesInfoCallback = void (LanguagesInfo result);
+  callback SpellCheckDictionaryChangedCallback =
+      void (SpellCheckDictionaryStatus result);
+  callback GetInputMethodsCallback = void (InputMethodsInfo result);
+  callback InputMethodEnabledDisabledCallback = void (DOMString id);

[stevenjb, 2015/04/24 00:00:20]

This name is a bit odd, see below.

+
+  interface Functions {
+    // Gets information about the available languages.
+    static void getLanguagesInfo(GetLanguagesInfoCallback callback);
+
+    // Changes the prospective locale. Takes effect after restarting Chrome.
+    static void setUILanguage(DOMString languageCode);
+
+    // Sets the accepted languages.
+    static void setLanguageList(DOMString[] languageCodes);
+
+    // Attempts to download the spell check dictionary after a failure.

[not at google - send to devlin, 2015/04/24 16:53:43]

what triggers the fetch in the first place?

[michaelpg, 2015/04/24 19:08:03]

In current Settings, if a d/l fails there's a "Retry" button the user may click.

[not at google - send to devlin, 2015/04/24 20:07:25]

Not really what I asked, but it sounds like the answer is that it's
automatically triggered at some point and this page is only expected to know to
Retry.

However - how will it know? There is an event with the current status, but what
about if the webui page isn't open at the time?

[michaelpg, 2015/04/25 02:49:16]

Sorry, I misread your question. The initial download happens in
SpellcheckService's listener for the spellcheck.dictionary pref change -- which
would be triggered when you click the "use this language for spell checking"
button.

You're right, this API was supposed to have a getter for the dictionary status.
My API outline doc had a getSpellCheckInfo function to get that info as well as
the two properties from LanguagesInfo you called out above.

I'll upload v2 when I hear back from shuchen.

+    static void retrySpellCheckDictionaryDownload();
+
+    // Gets all supported input methods, including IMEs.
+    static void getInputMethods(GetInputMethodsCallback callback);
+
+    // Enables or disables the input method.
+    static void setInputMethodEnabled(DOMString inputMethodId, boolean enabled);

[stevenjb, 2015/04/24 00:00:20]

Can more than one input method be enabled at once?

I am curious (and a bit concerned) about how this interacts with
inputMethodPrivate.setCurrentInputMethod().

[michaelpg, 2015/04/24 19:08:03]

Yes, any number of input methods can be enabled. For example, I have US QWERTY
and Dvorak enabled. I switch between them using Alt+Shift, which has the same
effect as inputMethodPrivate.setCurrentInputMethod('qwerty ID'/'dvorak ID').

inputMethodPrivate.setCurrentInputMethod will fail unless the input method to
make active is already enabled.
https://code.google.com/p/chromium/codesearch#chromium/src/chrome/browser/chr...

The logic for setInputMethodEnabled is already implemented as a chrome.send call
in CrosLanguageOptionsHandler. But Settings doesn't directly set which input
method is current.

[michaelpg, 2015/05/09 01:12:29]

So I understand the confusion with the terms "enable/disable", even though
Settings doesn't control which input method is currently active.

Would the terms "add/remove" be better? As in, these input methods are added and
removed from the user's list of input methods.

+  };
+
+  interface Events {
+    // Called when the language used for spell checking changes or the
+    // dictionary download status changes.
+    static void onSpellCheckDictionaryChanged(
+        SpellCheckDictionaryChangedCallback callback);
+
+    // Called when an input method is enabled.
+    static void onInputMethodEnabled(
+        InputMethodEnabledDisabledCallback callback);
+
+    // Called when an input method is disabled.
+    static void onInputMethodDisabled(
+        InputMethodEnabledDisabledCallback callback);

[stevenjb, 2015/04/24 00:00:20]

Might these be better as a single event with a booelean 'enabled' state, e.g.
onInputMethodEnabledStateChanged(id, isEnabled)?

[michaelpg, 2015/04/24 19:08:03]

I haven't found a single instance of a callback with multiple arguments. I
assume that's possible, then?

[not at google - send to devlin, 2015/04/24 20:07:25]

It might be possible, though we do prefer bundling event state into a single
dictionary.

+  };
+};