输入法InputConnection

Posted 2020-09-20 cynchanpin

/**
 * 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。而且发送关键指令给应用程序。
 * <p>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.</p>
 *应用程序不应直接实现此接口，而是实现其子类BaseInputConnection。子类会保证应用程序在执行中不会停止执行。假如InputConnection添加了新的方法。

 * <h3>Implementing an IME or an editor</h3>
 * <p>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
 * <a href="{@docRoot}guide/topics/text/creating-input-method.html">
 * Creating an input method</a> 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.</p>
 *第二个要素：编辑器。

编辑器是用于接收输入法提交的文字并显示的控件。默认这个控件叫做EditText，可是非常多应用程序基于特定需求也会实现他们自己的控件。实现自己定义控件是一个大并且复杂的工作。
同一时候应用程序还要保证他们实现的控件符合android标准EditText行为规范。
控件须要和输入法保持沟通，控件能够通过InputConnection接收输入法提交的文字，通过InputMethodManager发送指令给输入法。
控件通过onCreateINputConnection得到自己的InputConnection对象。
 * <p>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.</p>
 *假如你实现了自己的输入法程序，你须要调用方法和应用程序保持沟通。而且确保你的输入法程序通过了大量应用程序的測试。比如浏览器、往控件中提交大量的数据，由于有些应用程序含有特定的输入规格。你须要处理特定输入规则。

记住，你的输入法程序不是唯一一个改变控件内文字内容的来源，故而对待你提交的text和你接收的数据，尽可能保持慎重。

 * <p>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.</p>
 *假如你实现了自己的编辑器，你就须要提供你自己实现的BaseInputConnection子类实例。此实例用于和输入法应用程序保持应答。
确保你的控件通过了大部分输入法的測试，由于他们的行为变化多端。

同一时候确保在多语言下进行測试，包含CJK或者从右到左的语言，比如arabic。

由于这些语言有非常多不同的输入要求。

当你对实现的控件的行为存有疑问时。你能够通话我们。或者模仿近期的android版本号的TextView实现。假如你确定在你的系统中使用它，请考虑清楚控件的文字输入可能让用户体验非常坏。
 * <h3>Cursors, selections and compositions</h3>
 * <p>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.</p>
 *在android中。光标和所选内容一件事。光标就是一个0内容的所选内容。因而在android中，他们能够互换。

不论什么方法提交在光标前行为就是在提交所选内容之前，同理。在光标之后。就是提交在所选内容之后一样的行为。

 * <p>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.</p>
 */
编辑器控件须要可以保持写作内容区域的能力，就像标准的编辑小部件一样。
写作区域会被应用特定样式。比如：android.text.Spanned#SPAN_COMPOSING，输入法使用这样来帮助用户保持和当前获取焦点的文字内容追踪的能力，通过setComposingText或者finishComposingText等方法。