輸入法InputConnection

輸入法InputConnection

/**
* The InputConnection interface is the communication channel from an
* {@link InputMethod} back to the application that is receiving its
* input. It is used to perform such things as reading text around the
* cursor, committing text to the text box, and sending raw key events
* to the application.
*InputConnection 是介於輸入法和應用程序之間的通信通道。應用程序接收InputConnection的輸入，InputConnection的作用就是循環從Cursor中讀取text，往輸入框中提交這些text。並且發送關鍵指令給應用程序。
*

Applications should never directly implement this interface, but
* instead subclass from {@link BaseInputConnection}. This will ensure
* that the application does not break when new methods are added to
* the interface.

*應用程序不應直接實現此接口，而是實現其子類BaseInputConnection。子類會保證應用程序在運行中不會停止運行，假如InputConnection增加了新的方法。
*

Implementing an IME or an editor

*

Text input is the result of the synergy of two essential components:
* an Input Method Engine (IME) and an editor. The IME can be a
* software keyboard, a handwriting interface, an emoji palette, a
* speech-to-text engine, and so on. There are typically several IMEs
* installed on any given Android device. In Android, IMEs extend
* {@link android.inputmethodservice.InputMethodService}.
* For more information about how to create an IME, see the
*
* Creating an input method guide.
*文字輸入是由兩個要素共同作用的結果。輸入法應用程序和控件。
第一個要素：輸入法應用程序。輸入法程序可以是軟鍵盤、手寫板、表情符號，語音輸入引擎等等。
android系統默認安裝了幾款輸入法程序在android設備上。在android中，輸入法應用程序繼承自InputMethodService。
* The editor is the component that receives text and displays it.
* Typically, this is an {@link android.widget.EditText} instance, but
* some applications may choose to implement their own editor for
* various reasons. This is a large and complicated task, and an
* application that does this needs to make sure the behavior is
* consistent with standard EditText behavior in Android. An editor
* needs to interact with the IME, receiving commands through
* this InputConnection interface, and sending commands through
* {@link android.view.inputmethod.InputMethodManager}. An editor
* should start by implementing
* {@link android.view.View#onCreateInputConnection(EditorInfo)}
* to return its own input connection.

*第二個要素：編輯器。編輯器是用於接收輸入法提交的文字並顯示的控件。默認這個控件叫做EditText，但是很多應用程序基於特定需求也會實現他們自己的控件。實現自定義控件是一個大而且復雜的工作。
同時應用程序還要保證他們實現的控件符合android標准EditText行為規范。
控件需要和輸入法保持溝通，控件可以通過InputConnection接收輸入法提交的文字，通過InputMethodManager發送指令給輸入法。
控件通過onCreateINputConnection得到自己的InputConnection對象。
*

If you are implementing your own IME, you will need to call the
* methods in this interface to interact with the application. Be sure
* to test your IME with a wide range of applications, including
* browsers and rich text editors, as some may have peculiarities you
* need to deal with. Remember your IME may not be the only source of
* changes on the text, and try to be as conservative as possible in
* the data you send and as liberal as possible in the data you
* receive.

*假如你實現了自己的輸入法程序，你需要調用方法和應用程序保持溝通。並且確保你的輸入法程序通過了大量應用程序的測試，例如浏覽器、往控件中提交大量的數據，因為有些應用程序含有特定的輸入規格，你需要處理特定輸入規則。
記住，你的輸入法程序不是唯一一個改變控件內文字內容的來源，故而對待你提交的text和你接收的數據，盡可能保持謹慎。
*

If you are implementing your own editor, you will probably need
* to provide your own subclass of {@link BaseInputConnection} to
* answer to the commands from IMEs. Please be sure to test your
* editor with as many IMEs as you can as their behavior can vary a
* lot. Also be sure to test with various languages, including CJK
* languages and right-to-left languages like Arabic, as these may
* have different input requirements. When in doubt about the
* behavior you should adopt for a particular call, please mimic the
* default TextView implementation in the latest Android version, and
* if you decide to drift from it, please consider carefully that
* inconsistencies in text edition behavior is almost universally felt
* as a bad thing by users.

*假如你實現了自己的編輯器，你就需要提供你自己實現的BaseInputConnection子類實例，此實例用於和輸入法應用程序保持應答。
確保你的控件通過了大部分輸入法的測試，因為他們的行為變化多端。同時確保在多語言下進行測試，包括CJK或者從右到左的語言，例如arabic。因為這些語言有很多不同的輸入要求。
當你對實現的控件的行為存有疑問時，你可以通話我們，或者模仿最近的android版本的TextView實現。假如你確定在你的系統中使用它，請考慮清楚控件的文字輸入可能讓用戶體驗很壞。
*

Cursors, selections and compositions

*

In Android, the cursor and the selection are one and the same
* thing. A "cursor" is just the special case of a zero-sized
* selection. As such, this documentation uses them
* interchangeably. Any method acting "before the cursor" would act
* before the start of the selection if there is one, and any method
* acting "after the cursor" would act after the end of the
* selection.

*在android中，光標和所選內容一件事。光標就是一個0內容的所選內容。因而在android中，他們可以互換。
任何方法提交在光標前行為就是在提交所選內容之前，同理，在光標之後，就是提交在所選內容之後一樣的行為。
*

An editor needs to be able to keep track of a currently
* "composing" region, like the standard edition widgets do. The
* composition is marked in a specific style: see
* {@link android.text.Spanned#SPAN_COMPOSING}. IMEs use this to help
* the user keep track of what part of the text they are currently
* focusing on, and interact with the editor using
* {@link InputConnection#setComposingText(CharSequence, int)},
* {@link InputConnection#setComposingRegion(int, int)} and
* {@link InputConnection#finishComposingText()}.
* The composing region and the selection are completely independent
* of each other, and the IME may use them however they see fit.

*/
編輯器控件需要能夠保持寫作內容區域的能力，就像標准的編輯小部件一樣。
寫作區域會被應用特定樣式，例如：android.text.Spanned#SPAN_COMPOSING，輸入法使用這樣來幫助用戶保持和當前獲取焦點的文字內容追蹤的能力，通過setComposingText或者finishComposingText等方法。