android api (82) —— InputConnection [輸入法]

正文

　　一、結構

public interface InputConnection

        

android.view.inputmethod.InputConnection

 

間接子類

BaseInputConnection, InputConnectionWrapper

 

　　二、概述

　　　　 InputConnection接口是接收輸入的應用程序與InputMethod間的通訊通道。它可以完成以下功能，如讀取光標周圍的文本，向文本框提交文本，向應用程序提交原始按鍵事件。

 BaseInputConnection的子類應實現這一接口。

 

　　三、常量

　　public static final int GET_EXTRACTED_TEXT_MONITOR

　　標志，用在getExtractedText(ExtractedTextRequest, int)中，表示提取的文本變化時你想接收到更新。

　　常量值: 1 (0x00000001)

 

　　public static final int GET_TEXT_WITH_STYLES

　　標志，用在getTextAfterCursor(int, int)和getTextBeforeCursor(int, int)中，表明返回的文本中包含樣式。不設置時，你將僅接收原始文本。設置時，你將收到復合的CharSequence，包括文本和樣式段。

　　常量值: 1 (0x00000001)

 

　　四、公共方法

　　public abstract boolean beginBatchEdit ()

　　通知編輯器你將開始批量編輯操作。編輯器盡量避免向你發送狀態更新，直到調用endBatchEdit()為止。

 

　　public abstract boolean clearMetaKeyStates (int states)

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

　　參數

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

　　返回值

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

 

　　public abstract boolean commitCompletion (CompletionInfo text)

　　提交用戶的選擇，選擇先前向 InputMethodSession.displayCompletions()提交的選項中的一個。其結果就像用戶從實際UI中做出一樣。

　　參數

　　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 ()

　　調用endBatchEdit()方法通知編輯器之前開始的批量編輯已完成。

 

　　public abstract boolean finishComposingText ()

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

 

　　public abstract int getCursorCapsMode (int reqModes)

　　取得當前光標位置的文本的大小寫狀態。參見TextUtils.getCapsMode 取得更多信息。此方法在輸入連接(connection)無效（如線程沖突）或客戶端等待時間過長（等待幾秒返回）時可能會失敗。上述情況時返回0。

　　參數

　　　　　　reqModes       依據TextUtils.getCapsMode的定義取得期望的狀態。通過已定義的常數，你可以輕易地傳遞TextBoxAttribute.contentType到當前。

　　返回值

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

 

　　public abstract ExtractedText getExtractedText (ExtractedTextRequest request, int flags)

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

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

　　參數

　　request  描述文本如何返回

　　flags        控制客戶端的附加選項，0或GET_EXTRACTED_TEXT_MONITOR

　　返回值

           　　返回一個ExtractedText對象描述文本視窗的狀態，及所包含的提取文本。

 

　　public abstract CharSequence getSelectedText (int flags)

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

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

　　參數

　　flags        提供附加選項控制，控制文本如何返回。可為0 或 GET_TEXT_WITH_STYLES

　　返回值

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

 

　　public abstract CharSequence getTextAfterCursor (int n, int flags)

　　取得當前光標位置後的 n 個字符文本。

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

　　參數

　　n      期望的文本長度

　　flags        提供附加選項控制，控制文本如何返回。可為0 或 GET_TEXT_WITH_STYLES

　　返回值

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

 

　　public abstract CharSequence getTextBeforeCursor (int n, int flags)

　　取得當前光標位置前的 n 個字符文本。

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

　　參數

　　n      期望的文本長度

　　flags        提供附加選項控制，控制文本如何返回。可為0 或 GET_TEXT_WITH_STYLES

　　返回值

             　 返回當前光標前的文本，返回的文本長度可能小於 n

 

　　public abstract boolean performContextMenuAction (int id)

　　在區域中執行調用上下文菜單動作，其id可能下列之一：selectAll, startSelectingText, stopSelectingText, cut, copy, paste, copyUrl, 或 switchInputMethod。

 

　　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）確定鍵盤類型。

在你向本API發送的所有按鍵事件中，你可能希望設置KeyEvent.FLAG_SOFT_KEYBOARD標志，但這一標志不可設置。

　　參數

　　event       按鍵事件

　　返回值

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

         參見

             KeyEvent

             NUMERIC

             PREDICTIVE

             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。