前言

　　本章內容是android.view.inputmethod.InputConnection，為輸入法相關章節，版本為Android 2.3 r1，翻譯來自"六必治"，歡迎大家訪問他的部落格：http://www.cnblogs.com/zcmky/，再次感謝"六必治" ！期待你加入Android API 中文的翻譯，聯絡我[email protected]。

宣告

　　歡迎轉載，但請保留文章原始出處:)

正文

　　一、結構

public interface InputConnection

android.view.inputmethod.InputConnection

間接子類

　　二、概述

　　　　 InputConnection介面是接收輸入的應用程式與間的通訊通道。它可以完成以下功能，如讀取游標周圍的文字，向文字框提交文字，嚮應用程式提交原始按鍵事件。

　　三、常量

　　public static final int GET_EXTRACTED_TEXT_MONITOR

　　常量值: 1 (0x00000001)

　　public static final int GET_TEXT_WITH_STYLES

　　常量值: 1 (0x00000001)

　　四、公共方法

　　public abstract boolean beginBatchEdit ()

　　通知編輯器你將開始批量編輯操作。編輯器儘量避免向你傳送狀態更新，直到呼叫

　　public abstract boolean clearMetaKeyStates (int states)

　　在指定的輸入連線中清除指定的元鍵(meta key)按下狀態。

　　引數

　　states 清除的狀態，可以是KeyEvent.getMetaState()中的一位或多位結果。

　　返回值

　 成功返回true，當連線無效時返回flase。

　　public abstract boolean commitCompletion (CompletionInfo text)

　　引數

　　text 提交的結果。

　　返回值

　 成功返回true，當連線無效時返回flase。

　　public abstract boolean commitText (CharSequence text, int newCursorPosition)

　　向文字框提交文字並設定新的游標位置。之前設定的正編輯文字將自動刪除。

　　引數

　　text 提交的文字。

　　newCursorPosition 文字範圍內新的游標位置。如果大於0，從提交文字末尾－1處計起；<= 0，提交文字開始處計起。所以值為1時，游標將定位於你剛剛插入文字之後。注意你不能游標定位於提交文字中，因為編輯器可以修改你提供的文字，所以不必將游標定位在哪。

　　返回值

　 成功返回true，當連線無效時返回flase。

　　public abstract boolean deleteSurroundingText (int leftLength, int rightLength)

　　刪除當前游標前的leftLength個字元，並刪除當前游標後的rightLength個字元，不包聯想輸入(composing)的文字。

　　引數

　　leftLength 刪除的當前游標之前字元個數。

　　rightLength 刪除的當前游標之後字元個數。

　　返回值

　 成功返回true，當連線無效時返回flase。

　　public abstract boolean endBatchEdit ()

　　呼叫方法通知編輯器之前開始的批量編輯已完成。

　　public abstract boolean finishComposingText ()

　　強制結束文字編輯器，無論聯想輸入(composing text)是否啟用。文字保持不變，移除任何與此文字的編輯樣式或其他狀態。游標保持不變。

　　public abstract int getCursorCapsMode (int reqModes)

　　取得當前游標位置的文字的大小寫狀態。參見 取得更多資訊。此方法在輸入連線(connection)無效（如執行緒衝突）或客戶端等待時間過長（等待幾秒返回）時可能會失敗。上述情況時返回0。

　　引數

　　返回值

　 返回當前有效的大小寫狀態。

　　public abstract ExtractedText getExtractedText (ExtractedTextRequest request, int flags)

　　獲取當前輸入連線的編輯器中的當前文字，並監視是否有變化。函式返回當前文字，當文字變化時輸入連線可選擇性向輸入法傳送更新。

　　此方法在輸入聯接無效時（如執行緒衝突）或客戶端等待時間過長（等待幾秒返回）時可能會失敗。上述情況時返回null值。

　　引數

　　request 描述文字如何返回

　　返回值

　　返回一個ExtractedText物件描述文字視窗的狀態，及所包含的提取文字。

　　public abstract CharSequence getSelectedText (int flags)

　　如果有的話取得所選的文字。

　　此方法在輸入連線無效時（如執行緒衝突）或客戶端等待時間過長（等待幾秒返回）時可能會失敗。上述情況時返回null值。

　　引數

　　返回值

　 如果有的話返回當前選取文字，如果沒有文字被選中返回null。

　　public abstract CharSequence getTextAfterCursor (int n, int flags)

　　取得當前游標位置後的 n 個字元文字。

　　此方法在輸入連線無效時（如執行緒衝突）或客戶端等待時間過長（等待幾秒返回）時可能會失敗。上述情況時返回null值。

　　引數

　　n 期望的文字長度

　　返回值

　 返回當前游標後的文字，返回的文字長度可能小於 n

　　public abstract CharSequence getTextBeforeCursor (int n, int flags)

　　取得當前游標位置前的 n 個字元文字。

　　本此方法在輸入連線無效（如執行緒衝突）或客戶端等待時間過長（等待幾秒返回）時可能會失敗。上述情況時返回null值。

　　引數

　　n 期望的文字長度

　　返回值

　 返回當前游標前的文字，返回的文字長度可能小於 n

　　public abstract boolean performContextMenuAction (int id)

　　public abstract boolean performEditorAction (int editorAction)

　　讓編輯器執行一個它可以完成的操作。

　　引數

　　editorAction 必須是動作常量EditorInfo.editorType中的一個，如EditorInfo.EDITOR_ACTION_GO。

　　返回值

　 成功返回true,如輸入連線無效返回false。

　　public abstract boolean performPrivateCommand (String action, Bundle data)

　　API從輸入法向所連線的編輯器傳送私有命令。這可用於提供僅用於特定輸入法及其客戶端功能的特定域（domain-specific）。注意，因為InputConnection協議是非同步的，你無法取回結果或知道客戶端是否懂得命令；你可能使用 EditorInfo來確定客戶端是否支援某一命令。

　　引數

　　action 要執行的命令名稱。必須是作用域名，字首你自己的包名，這樣不同的開發者就不會建立讓人衝突的命令。

　　data 命令中的資料

　　返回值

　 當命令傳送後返回true（無論相關的編輯是否理解它），如輸入連線無效返回false。

　　public abstract boolean reportFullscreenMode (boolean enabled)

　　由IME呼叫，通知客戶端將在全屏與普通模式間切換。它在 InputMethodService的標準實現中被呼叫。

　　public abstract boolean sendKeyEvent (KeyEvent event)

　　向當前輸入連線所附著的程序傳送按鍵事件。事件像普通按鍵事件一樣由當前焦點，通常是提供InputConnection的檢視。但由於協議的非同步性這一點並不總是這樣，焦點可能在事件收到時發生改變。

本方法可用於嚮應用程式傳送按鍵事件。如螢幕鍵盤可以用這一方法模擬硬體鍵盤。標準鍵盤有三種：數字（12鍵），預測鍵盤（20鍵）和字母（QWERTY）。你可以通過事件的裝置碼（device id）確定鍵盤型別。

　　引數

　　event 按鍵事件

　　返回值

　 成功返回true，當輸入連線無效返回false。

參見

ALPHA

　　public abstract boolean setComposingRegion (int start, int end)

　　將特定區域設為正在編輯文字。以前設定的正在編輯文字自動移除。文字使用預設正在編輯文字樣式。(稽核注：”composing text”的翻譯還需要後期用例子來推測其含義。)

　　引數

　　start 正在編輯文字開始的位置

　　end 正在編輯文字結束的位置。

　　返回值

　 成功返回true，當輸入聯接無效時返回false。

　　public abstract boolean setComposingText (CharSequence text, int newCursorPosition)

　　將當前的游標旁正在聯想文字(composing text)替代為給定文字，並設定新游標位置。以前設定的正在編輯文字自動移除。（譯者注：

InputConnection ic = getCurrentInputConnection();

ic.setComposingText("Composi", 1);

　　）

　　引數

　　text 如必要正在編輯文字有樣式。如文字沒有附帶樣式物件，正在編輯文字將應用預設樣式。見如何在文字上附加樣式{#link android.text.Spanned}。{#link android.text.SpannableString}和{#link 　　android.text.SpannableStringBuilder}是兩種介面實現方式。

　　newCursorPosition 文字範圍內新的游標位置。如果大於0，從提交文字末尾－1處計起；<= 0，提交文字開始處計起。所以值為1時，游標將定位於你剛剛插入文字之後。注意你不能游標定位於提交文字中，因為編輯器可以修改你提供的文字，所以不必將游標定位在哪。

　　返回值

　 成功返回true，當輸入聯接無效時返回false。

　　public abstract boolean setSelection (int start, int end)

　　設定文字編輯器的選定文字。設定到當前游標時，開始與結束取相同值。

　　返回值

　　成功返回true，當輸入聯接無效時返回false。

　　五、補充