1/*
2 * Copyright (C) 2015 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16package android.view;
17
18import static com.android.internal.util.Preconditions.checkArgument;
19
20import static java.lang.Character.MIN_VALUE;
21
22import android.annotation.Nullable;
23import android.graphics.drawable.Icon;
24import android.os.Parcel;
25import android.os.Parcelable;
26
27/**
28 * Information about a Keyboard Shortcut.
29 */
30public final class KeyboardShortcutInfo implements Parcelable {
31    private final CharSequence mLabel;
32    private final Icon mIcon;
33    private final char mBaseCharacter;
34    private final int mKeycode;
35    private final int mModifiers;
36
37    /**
38     * @param label The label that identifies the action performed by this shortcut.
39     * @param icon An icon that identifies the action performed by this shortcut.
40     * @param keycode The keycode that triggers the shortcut. This should be a valid constant
41     *     defined in {@link KeyEvent}.
42     * @param modifiers The set of modifiers that, combined with the key, trigger the shortcut.
43     *     These should be a combination of {@link KeyEvent#META_CTRL_ON},
44     *     {@link KeyEvent#META_SHIFT_ON}, {@link KeyEvent#META_META_ON},
45     *     {@link KeyEvent#META_ALT_ON}, {@link KeyEvent#META_FUNCTION_ON} and
46     *     {@link KeyEvent#META_SYM_ON}.
47     *
48     * @hide
49     */
50    public KeyboardShortcutInfo(
51            @Nullable CharSequence label, @Nullable Icon icon, int keycode, int modifiers) {
52        mLabel = label;
53        mIcon = icon;
54        mBaseCharacter = MIN_VALUE;
55        checkArgument(keycode >= KeyEvent.KEYCODE_UNKNOWN && keycode <= KeyEvent.getMaxKeyCode());
56        mKeycode = keycode;
57        mModifiers = modifiers;
58    }
59
60    /**
61     * @param label The label that identifies the action performed by this shortcut.
62     * @param keycode The keycode that triggers the shortcut. This should be a valid constant
63     *     defined in {@link KeyEvent}.
64     * @param modifiers The set of modifiers that, combined with the key, trigger the shortcut.
65     *     These should be a combination of {@link KeyEvent#META_CTRL_ON},
66     *     {@link KeyEvent#META_SHIFT_ON}, {@link KeyEvent#META_META_ON},
67     *     {@link KeyEvent#META_ALT_ON}, {@link KeyEvent#META_FUNCTION_ON} and
68     *     {@link KeyEvent#META_SYM_ON}.
69     */
70    public KeyboardShortcutInfo(CharSequence label, int keycode, int modifiers) {
71        this(label, null, keycode, modifiers);
72    }
73
74    /**
75     * @param label The label that identifies the action performed by this shortcut.
76     * @param baseCharacter The character that triggers the shortcut.
77     * @param modifiers The set of modifiers that, combined with the key, trigger the shortcut.
78     *     These should be a combination of {@link KeyEvent#META_CTRL_ON},
79     *     {@link KeyEvent#META_SHIFT_ON}, {@link KeyEvent#META_META_ON},
80     *     {@link KeyEvent#META_ALT_ON}, {@link KeyEvent#META_FUNCTION_ON} and
81     *     {@link KeyEvent#META_SYM_ON}.
82     */
83    public KeyboardShortcutInfo(CharSequence label, char baseCharacter, int modifiers) {
84        mLabel = label;
85        checkArgument(baseCharacter != MIN_VALUE);
86        mBaseCharacter = baseCharacter;
87        mKeycode = KeyEvent.KEYCODE_UNKNOWN;
88        mModifiers = modifiers;
89        mIcon = null;
90    }
91
92    private KeyboardShortcutInfo(Parcel source) {
93        mLabel = source.readCharSequence();
94        mIcon = source.readParcelable(null);
95        mBaseCharacter = (char) source.readInt();
96        mKeycode = source.readInt();
97        mModifiers = source.readInt();
98    }
99
100    /**
101     * Returns the label to be used to describe this shortcut.
102     */
103    @Nullable
104    public CharSequence getLabel() {
105        return mLabel;
106    }
107
108    /**
109     * Returns the icon to be used to describe this shortcut.
110     *
111     * @hide
112     */
113    @Nullable
114    public Icon getIcon() {
115        return mIcon;
116    }
117
118    /**
119     * Returns the base keycode that, combined with the modifiers, triggers this shortcut. If the
120     * base character was set instead, returns {@link KeyEvent#KEYCODE_UNKNOWN}. Valid keycodes are
121     * defined as constants in {@link KeyEvent}.
122     */
123    public int getKeycode() {
124        return mKeycode;
125    }
126
127    /**
128     * Returns the base character that, combined with the modifiers, triggers this shortcut. If the
129     * keycode was set instead, returns {@link Character#MIN_VALUE}.
130     */
131    public char getBaseCharacter() {
132        return mBaseCharacter;
133    }
134
135    /**
136     * Returns the set of modifiers that, combined with the key, trigger this shortcut. These can
137     * be a combination of {@link KeyEvent#META_CTRL_ON}, {@link KeyEvent#META_SHIFT_ON},
138     * {@link KeyEvent#META_META_ON}, {@link KeyEvent#META_ALT_ON},
139     * {@link KeyEvent#META_FUNCTION_ON} and {@link KeyEvent#META_SYM_ON}.
140     */
141    public int getModifiers() {
142        return mModifiers;
143    }
144
145    @Override
146    public int describeContents() {
147        return 0;
148    }
149
150    @Override
151    public void writeToParcel(Parcel dest, int flags) {
152        dest.writeCharSequence(mLabel);
153        dest.writeParcelable(mIcon, 0);
154        dest.writeInt(mBaseCharacter);
155        dest.writeInt(mKeycode);
156        dest.writeInt(mModifiers);
157    }
158
159    public static final Creator<KeyboardShortcutInfo> CREATOR =
160            new Creator<KeyboardShortcutInfo>() {
161        public KeyboardShortcutInfo createFromParcel(Parcel source) {
162            return new KeyboardShortcutInfo(source);
163        }
164        public KeyboardShortcutInfo[] newArray(int size) {
165            return new KeyboardShortcutInfo[size];
166        }
167    };
168}