Java tutorial
/* * Copyright (C) 2006 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.text.method; import android.annotation.UnsupportedAppUsage; import android.text.Editable; import android.text.NoCopySpan; import android.text.Spannable; import android.text.Spanned; import android.view.KeyCharacterMap; import android.view.KeyEvent; import android.view.View; /** * This base class encapsulates the behavior for tracking the state of * meta keys such as SHIFT, ALT and SYM as well as the pseudo-meta state of selecting text. * <p> * Key listeners that care about meta state should inherit from this class; * you should not instantiate this class directly in a client. * </p><p> * This class provides two mechanisms for tracking meta state that can be used * together or independently. * </p> * <ul> * <li>Methods such as {@link #handleKeyDown(long, int, KeyEvent)} and * {@link #getMetaState(long)} operate on a meta key state bit mask.</li> * <li>Methods such as {@link #onKeyDown(View, Editable, int, KeyEvent)} and * {@link #getMetaState(CharSequence, int)} operate on meta key state flags stored * as spans in an {@link Editable} text buffer. The spans only describe the current * meta key state of the text editor; they do not carry any positional information.</li> * </ul> * <p> * The behavior of this class varies according to the keyboard capabilities * described by the {@link KeyCharacterMap} of the keyboard device such as * the {@link KeyCharacterMap#getModifierBehavior() key modifier behavior}. * </p><p> * {@link MetaKeyKeyListener} implements chorded and toggled key modifiers. * When key modifiers are toggled into a latched or locked state, the state * of the modifier is stored in the {@link Editable} text buffer or in a * meta state integer managed by the client. These latched or locked modifiers * should be considered to be held <b>in addition to</b> those that the * keyboard already reported as being pressed in {@link KeyEvent#getMetaState()}. * In other words, the {@link MetaKeyKeyListener} augments the meta state * provided by the keyboard; it does not replace it. This distinction is important * to ensure that meta keys not handled by {@link MetaKeyKeyListener} such as * {@link KeyEvent#KEYCODE_CAPS_LOCK} or {@link KeyEvent#KEYCODE_NUM_LOCK} are * taken into consideration. * </p><p> * To ensure correct meta key behavior, the following pattern should be used * when mapping key codes to characters: * </p> * <code> * private char getUnicodeChar(TextKeyListener listener, KeyEvent event, Editable textBuffer) { * // Use the combined meta states from the event and the key listener. * int metaState = event.getMetaState() | listener.getMetaState(textBuffer); * return event.getUnicodeChar(metaState); * } * </code> */ public abstract class MetaKeyKeyListener { /** * Flag that indicates that the SHIFT key is on. * Value equals {@link KeyEvent#META_SHIFT_ON}. */ public static final int META_SHIFT_ON = KeyEvent.META_SHIFT_ON; /** * Flag that indicates that the ALT key is on. * Value equals {@link KeyEvent#META_ALT_ON}. */ public static final int META_ALT_ON = KeyEvent.META_ALT_ON; /** * Flag that indicates that the SYM key is on. * Value equals {@link KeyEvent#META_SYM_ON}. */ public static final int META_SYM_ON = KeyEvent.META_SYM_ON; /** * Flag that indicates that the SHIFT key is locked in CAPS mode. */ public static final int META_CAP_LOCKED = KeyEvent.META_CAP_LOCKED; /** * Flag that indicates that the ALT key is locked. */ public static final int META_ALT_LOCKED = KeyEvent.META_ALT_LOCKED; /** * Flag that indicates that the SYM key is locked. */ public static final int META_SYM_LOCKED = KeyEvent.META_SYM_LOCKED; /** * @hide pending API review */ public static final int META_SELECTING = KeyEvent.META_SELECTING; // These bits are privately used by the meta key key listener. // They are deliberately assigned values outside of the representable range of an 'int' // so as not to conflict with any meta key states publicly defined by KeyEvent. private static final long META_CAP_USED = 1L << 32; private static final long META_ALT_USED = 1L << 33; private static final long META_SYM_USED = 1L << 34; private static final long META_CAP_PRESSED = 1L << 40; private static final long META_ALT_PRESSED = 1L << 41; private static final long META_SYM_PRESSED = 1L << 42; private static final long META_CAP_RELEASED = 1L << 48; private static final long META_ALT_RELEASED = 1L << 49; private static final long META_SYM_RELEASED = 1L << 50; private static final long META_SHIFT_MASK = META_SHIFT_ON | META_CAP_LOCKED | META_CAP_USED | META_CAP_PRESSED | META_CAP_RELEASED; private static final long META_ALT_MASK = META_ALT_ON | META_ALT_LOCKED | META_ALT_USED | META_ALT_PRESSED | META_ALT_RELEASED; private static final long META_SYM_MASK = META_SYM_ON | META_SYM_LOCKED | META_SYM_USED | META_SYM_PRESSED | META_SYM_RELEASED; private static final Object CAP = new NoCopySpan.Concrete(); private static final Object ALT = new NoCopySpan.Concrete(); private static final Object SYM = new NoCopySpan.Concrete(); private static final Object SELECTING = new NoCopySpan.Concrete(); private static final int PRESSED_RETURN_VALUE = 1; private static final int LOCKED_RETURN_VALUE = 2; /** * Resets all meta state to inactive. */ public static void resetMetaState(Spannable text) { text.removeSpan(CAP); text.removeSpan(ALT); text.removeSpan(SYM); text.removeSpan(SELECTING); } /** * Gets the state of the meta keys. * * @param text the buffer in which the meta key would have been pressed. * * @return an integer in which each bit set to one represents a pressed * or locked meta key. */ public static final int getMetaState(CharSequence text) { return getActive(text, CAP, META_SHIFT_ON, META_CAP_LOCKED) | getActive(text, ALT, META_ALT_ON, META_ALT_LOCKED) | getActive(text, SYM, META_SYM_ON, META_SYM_LOCKED) | getActive(text, SELECTING, META_SELECTING, META_SELECTING); } /** * Gets the state of the meta keys for a specific key event. * * For input devices that use toggled key modifiers, the `toggled' state * is stored into the text buffer. This method retrieves the meta state * for this event, accounting for the stored state. If the event has been * created by a device that does not support toggled key modifiers, like * a virtual device for example, the stored state is ignored. * * @param text the buffer in which the meta key would have been pressed. * @param event the event for which to evaluate the meta state. * @return an integer in which each bit set to one represents a pressed * or locked meta key. */ public static final int getMetaState(final CharSequence text, final KeyEvent event) { int metaState = event.getMetaState(); if (event.getKeyCharacterMap() .getModifierBehavior() == KeyCharacterMap.MODIFIER_BEHAVIOR_CHORDED_OR_TOGGLED) { metaState |= getMetaState(text); } return metaState; } // As META_SELECTING is @hide we should not mention it in public comments, hence the // omission in @param meta /** * Gets the state of a particular meta key. * * @param meta META_SHIFT_ON, META_ALT_ON, META_SYM_ON * @param text the buffer in which the meta key would have been pressed. * * @return 0 if inactive, 1 if active, 2 if locked. */ public static final int getMetaState(CharSequence text, int meta) { switch (meta) { case META_SHIFT_ON: return getActive(text, CAP, PRESSED_RETURN_VALUE, LOCKED_RETURN_VALUE); case META_ALT_ON: return getActive(text, ALT, PRESSED_RETURN_VALUE, LOCKED_RETURN_VALUE); case META_SYM_ON: return getActive(text, SYM, PRESSED_RETURN_VALUE, LOCKED_RETURN_VALUE); case META_SELECTING: return getActive(text, SELECTING, PRESSED_RETURN_VALUE, LOCKED_RETURN_VALUE); default: return 0; } } /** * Gets the state of a particular meta key to use with a particular key event. * * If the key event has been created by a device that does not support toggled * key modifiers, like a virtual keyboard for example, only the meta state in * the key event is considered. * * @param meta META_SHIFT_ON, META_ALT_ON, META_SYM_ON * @param text the buffer in which the meta key would have been pressed. * @param event the event for which to evaluate the meta state. * @return 0 if inactive, 1 if active, 2 if locked. */ public static final int getMetaState(final CharSequence text, final int meta, final KeyEvent event) { int metaState = event.getMetaState(); if (event.getKeyCharacterMap() .getModifierBehavior() == KeyCharacterMap.MODIFIER_BEHAVIOR_CHORDED_OR_TOGGLED) { metaState |= getMetaState(text); } if (META_SELECTING == meta) { // #getMetaState(long, int) does not support META_SELECTING, but we want the same // behavior as #getMetaState(CharSequence, int) so we need to do it here if ((metaState & META_SELECTING) != 0) { // META_SELECTING is only ever set to PRESSED and can't be LOCKED, so return 1 return 1; } return 0; } return getMetaState(metaState, meta); } private static int getActive(CharSequence text, Object meta, int on, int lock) { if (!(text instanceof Spanned)) { return 0; } Spanned sp = (Spanned) text; int flag = sp.getSpanFlags(meta); if (flag == LOCKED) { return lock; } else if (flag != 0) { return on; } else { return 0; } } /** * Call this method after you handle a keypress so that the meta * state will be reset to unshifted (if it is not still down) * or primed to be reset to unshifted (once it is released). */ public static void adjustMetaAfterKeypress(Spannable content) { adjust(content, CAP); adjust(content, ALT); adjust(content, SYM); } /** * Returns true if this object is one that this class would use to * keep track of any meta state in the specified text. */ public static boolean isMetaTracker(CharSequence text, Object what) { return what == CAP || what == ALT || what == SYM || what == SELECTING; } /** * Returns true if this object is one that this class would use to * keep track of the selecting meta state in the specified text. */ public static boolean isSelectingMetaTracker(CharSequence text, Object what) { return what == SELECTING; } private static void adjust(Spannable content, Object what) { int current = content.getSpanFlags(what); if (current == PRESSED) content.setSpan(what, 0, 0, USED); else if (current == RELEASED) content.removeSpan(what); } /** * Call this if you are a method that ignores the locked meta state * (arrow keys, for example) and you handle a key. */ protected static void resetLockedMeta(Spannable content) { resetLock(content, CAP); resetLock(content, ALT); resetLock(content, SYM); resetLock(content, SELECTING); } private static void resetLock(Spannable content, Object what) { int current = content.getSpanFlags(what); if (current == LOCKED) content.removeSpan(what); } /** * Handles presses of the meta keys. */ public boolean onKeyDown(View view, Editable content, int keyCode, KeyEvent event) { if (keyCode == KeyEvent.KEYCODE_SHIFT_LEFT || keyCode == KeyEvent.KEYCODE_SHIFT_RIGHT) { press(content, CAP); return true; } if (keyCode == KeyEvent.KEYCODE_ALT_LEFT || keyCode == KeyEvent.KEYCODE_ALT_RIGHT || keyCode == KeyEvent.KEYCODE_NUM) { press(content, ALT); return true; } if (keyCode == KeyEvent.KEYCODE_SYM) { press(content, SYM); return true; } return false; // no super to call through to } private void press(Editable content, Object what) { int state = content.getSpanFlags(what); if (state == PRESSED) ; // repeat before use else if (state == RELEASED) content.setSpan(what, 0, 0, LOCKED); else if (state == USED) ; // repeat after use else if (state == LOCKED) content.removeSpan(what); else content.setSpan(what, 0, 0, PRESSED); } /** * Start selecting text. * @hide pending API review */ @UnsupportedAppUsage public static void startSelecting(View view, Spannable content) { content.setSpan(SELECTING, 0, 0, PRESSED); } /** * Stop selecting text. This does not actually collapse the selection; * call {@link android.text.Selection#setSelection} too. * @hide pending API review */ @UnsupportedAppUsage public static void stopSelecting(View view, Spannable content) { content.removeSpan(SELECTING); } /** * Handles release of the meta keys. */ public boolean onKeyUp(View view, Editable content, int keyCode, KeyEvent event) { if (keyCode == KeyEvent.KEYCODE_SHIFT_LEFT || keyCode == KeyEvent.KEYCODE_SHIFT_RIGHT) { release(content, CAP, event); return true; } if (keyCode == KeyEvent.KEYCODE_ALT_LEFT || keyCode == KeyEvent.KEYCODE_ALT_RIGHT || keyCode == KeyEvent.KEYCODE_NUM) { release(content, ALT, event); return true; } if (keyCode == KeyEvent.KEYCODE_SYM) { release(content, SYM, event); return true; } return false; // no super to call through to } private void release(Editable content, Object what, KeyEvent event) { int current = content.getSpanFlags(what); switch (event.getKeyCharacterMap().getModifierBehavior()) { case KeyCharacterMap.MODIFIER_BEHAVIOR_CHORDED_OR_TOGGLED: if (current == USED) content.removeSpan(what); else if (current == PRESSED) content.setSpan(what, 0, 0, RELEASED); break; default: content.removeSpan(what); break; } } public void clearMetaKeyState(View view, Editable content, int states) { clearMetaKeyState(content, states); } public static void clearMetaKeyState(Editable content, int states) { if ((states & META_SHIFT_ON) != 0) content.removeSpan(CAP); if ((states & META_ALT_ON) != 0) content.removeSpan(ALT); if ((states & META_SYM_ON) != 0) content.removeSpan(SYM); if ((states & META_SELECTING) != 0) content.removeSpan(SELECTING); } /** * Call this if you are a method that ignores the locked meta state * (arrow keys, for example) and you handle a key. */ public static long resetLockedMeta(long state) { if ((state & META_CAP_LOCKED) != 0) { state &= ~META_SHIFT_MASK; } if ((state & META_ALT_LOCKED) != 0) { state &= ~META_ALT_MASK; } if ((state & META_SYM_LOCKED) != 0) { state &= ~META_SYM_MASK; } return state; } // --------------------------------------------------------------------- // Version of API that operates on a state bit mask // --------------------------------------------------------------------- /** * Gets the state of the meta keys. * * @param state the current meta state bits. * * @return an integer in which each bit set to one represents a pressed * or locked meta key. */ public static final int getMetaState(long state) { int result = 0; if ((state & META_CAP_LOCKED) != 0) { result |= META_CAP_LOCKED; } else if ((state & META_SHIFT_ON) != 0) { result |= META_SHIFT_ON; } if ((state & META_ALT_LOCKED) != 0) { result |= META_ALT_LOCKED; } else if ((state & META_ALT_ON) != 0) { result |= META_ALT_ON; } if ((state & META_SYM_LOCKED) != 0) { result |= META_SYM_LOCKED; } else if ((state & META_SYM_ON) != 0) { result |= META_SYM_ON; } return result; } /** * Gets the state of a particular meta key. * * @param state the current state bits. * @param meta META_SHIFT_ON, META_ALT_ON, or META_SYM_ON * * @return 0 if inactive, 1 if active, 2 if locked. */ public static final int getMetaState(long state, int meta) { switch (meta) { case META_SHIFT_ON: if ((state & META_CAP_LOCKED) != 0) return LOCKED_RETURN_VALUE; if ((state & META_SHIFT_ON) != 0) return PRESSED_RETURN_VALUE; return 0; case META_ALT_ON: if ((state & META_ALT_LOCKED) != 0) return LOCKED_RETURN_VALUE; if ((state & META_ALT_ON) != 0) return PRESSED_RETURN_VALUE; return 0; case META_SYM_ON: if ((state & META_SYM_LOCKED) != 0) return LOCKED_RETURN_VALUE; if ((state & META_SYM_ON) != 0) return PRESSED_RETURN_VALUE; return 0; default: return 0; } } /** * Call this method after you handle a keypress so that the meta * state will be reset to unshifted (if it is not still down) * or primed to be reset to unshifted (once it is released). Takes * the current state, returns the new state. */ public static long adjustMetaAfterKeypress(long state) { if ((state & META_CAP_PRESSED) != 0) { state = (state & ~META_SHIFT_MASK) | META_SHIFT_ON | META_CAP_USED; } else if ((state & META_CAP_RELEASED) != 0) { state &= ~META_SHIFT_MASK; } if ((state & META_ALT_PRESSED) != 0) { state = (state & ~META_ALT_MASK) | META_ALT_ON | META_ALT_USED; } else if ((state & META_ALT_RELEASED) != 0) { state &= ~META_ALT_MASK; } if ((state & META_SYM_PRESSED) != 0) { state = (state & ~META_SYM_MASK) | META_SYM_ON | META_SYM_USED; } else if ((state & META_SYM_RELEASED) != 0) { state &= ~META_SYM_MASK; } return state; } /** * Handles presses of the meta keys. */ public static long handleKeyDown(long state, int keyCode, KeyEvent event) { if (keyCode == KeyEvent.KEYCODE_SHIFT_LEFT || keyCode == KeyEvent.KEYCODE_SHIFT_RIGHT) { return press(state, META_SHIFT_ON, META_SHIFT_MASK, META_CAP_LOCKED, META_CAP_PRESSED, META_CAP_RELEASED, META_CAP_USED); } if (keyCode == KeyEvent.KEYCODE_ALT_LEFT || keyCode == KeyEvent.KEYCODE_ALT_RIGHT || keyCode == KeyEvent.KEYCODE_NUM) { return press(state, META_ALT_ON, META_ALT_MASK, META_ALT_LOCKED, META_ALT_PRESSED, META_ALT_RELEASED, META_ALT_USED); } if (keyCode == KeyEvent.KEYCODE_SYM) { return press(state, META_SYM_ON, META_SYM_MASK, META_SYM_LOCKED, META_SYM_PRESSED, META_SYM_RELEASED, META_SYM_USED); } return state; } private static long press(long state, int what, long mask, long locked, long pressed, long released, long used) { if ((state & pressed) != 0) { // repeat before use } else if ((state & released) != 0) { state = (state & ~mask) | what | locked; } else if ((state & used) != 0) { // repeat after use } else if ((state & locked) != 0) { state &= ~mask; } else { state |= what | pressed; } return state; } /** * Handles release of the meta keys. */ public static long handleKeyUp(long state, int keyCode, KeyEvent event) { if (keyCode == KeyEvent.KEYCODE_SHIFT_LEFT || keyCode == KeyEvent.KEYCODE_SHIFT_RIGHT) { return release(state, META_SHIFT_ON, META_SHIFT_MASK, META_CAP_PRESSED, META_CAP_RELEASED, META_CAP_USED, event); } if (keyCode == KeyEvent.KEYCODE_ALT_LEFT || keyCode == KeyEvent.KEYCODE_ALT_RIGHT || keyCode == KeyEvent.KEYCODE_NUM) { return release(state, META_ALT_ON, META_ALT_MASK, META_ALT_PRESSED, META_ALT_RELEASED, META_ALT_USED, event); } if (keyCode == KeyEvent.KEYCODE_SYM) { return release(state, META_SYM_ON, META_SYM_MASK, META_SYM_PRESSED, META_SYM_RELEASED, META_SYM_USED, event); } return state; } private static long release(long state, int what, long mask, long pressed, long released, long used, KeyEvent event) { switch (event.getKeyCharacterMap().getModifierBehavior()) { case KeyCharacterMap.MODIFIER_BEHAVIOR_CHORDED_OR_TOGGLED: if ((state & used) != 0) { state &= ~mask; } else if ((state & pressed) != 0) { state |= what | released; } break; default: state &= ~mask; break; } return state; } /** * Clears the state of the specified meta key if it is locked. * @param state the meta key state * @param which meta keys to clear, may be a combination of {@link #META_SHIFT_ON}, * {@link #META_ALT_ON} or {@link #META_SYM_ON}. */ public long clearMetaKeyState(long state, int which) { if ((which & META_SHIFT_ON) != 0 && (state & META_CAP_LOCKED) != 0) { state &= ~META_SHIFT_MASK; } if ((which & META_ALT_ON) != 0 && (state & META_ALT_LOCKED) != 0) { state &= ~META_ALT_MASK; } if ((which & META_SYM_ON) != 0 && (state & META_SYM_LOCKED) != 0) { state &= ~META_SYM_MASK; } return state; } /** * The meta key has been pressed but has not yet been used. */ private static final int PRESSED = Spannable.SPAN_MARK_MARK | (1 << Spannable.SPAN_USER_SHIFT); /** * The meta key has been pressed and released but has still * not yet been used. */ private static final int RELEASED = Spannable.SPAN_MARK_MARK | (2 << Spannable.SPAN_USER_SHIFT); /** * The meta key has been pressed and used but has not yet been released. */ private static final int USED = Spannable.SPAN_MARK_MARK | (3 << Spannable.SPAN_USER_SHIFT); /** * The meta key has been pressed and released without use, and then * pressed again; it may also have been released again. */ private static final int LOCKED = Spannable.SPAN_MARK_MARK | (4 << Spannable.SPAN_USER_SHIFT); }