MenuItemCompat.java revision 0574ca37da4619afe4e26753f5a1b4de314b6565 
1/*
2 * Copyright (C) 2011 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 */
16
17package android.support.v4.view;
18
19import android.view.MenuItem;
20import android.view.View;
21
22/**
23 * Helper for accessing features in {@link android.view.MenuItem}
24 * introduced after API level 4 in a backwards compatible fashion.
25 */
26public class MenuItemCompat {
27
28    /**
29     * Never show this item as a button in an Action Bar.
30     */
31    public static final int SHOW_AS_ACTION_NEVER = 0;
32
33    /**
34     * Show this item as a button in an Action Bar if the system
35     * decides there is room for it.
36     */
37    public static final int SHOW_AS_ACTION_IF_ROOM = 1;
38
39    /**
40     * Always show this item as a button in an Action Bar. Use sparingly!
41     * If too many items are set to always show in the Action Bar it can
42     * crowd the Action Bar and degrade the user experience on devices with
43     * smaller screens. A good rule of thumb is to have no more than 2
44     * items set to always show at a time.
45     */
46    public static final int SHOW_AS_ACTION_ALWAYS = 2;
47
48    /**
49     * When this item is in the action bar, always show it with a
50     * text label even if it also has an icon specified.
51     */
52    public static final int SHOW_AS_ACTION_WITH_TEXT = 4;
53
54    /**
55     * This item's action view collapses to a normal menu item.
56     * When expanded, the action view temporarily takes over
57     * a larger segment of its container.
58     */
59    public static final int SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW = 8;
60
61    /**
62     * Interface for the full API.
63     */
64    interface MenuVersionImpl {
65        public boolean setShowAsAction(MenuItem item, int actionEnum);
66        public MenuItem setActionView(MenuItem item, View view);
67    }
68
69    /**
70     * Interface implementation that doesn't use anything about v4 APIs.
71     */
72    static class BaseMenuVersionImpl implements MenuVersionImpl {
73        @Override
74        public boolean setShowAsAction(MenuItem item, int actionEnum) {
75            return false;
76        }
77
78        @Override
79        public MenuItem setActionView(MenuItem item, View view) {
80            return item;
81        }
82    }
83
84    /**
85     * Interface implementation for devices with at least v11 APIs.
86     */
87    static class HoneycombMenuVersionImpl implements MenuVersionImpl {
88        @Override
89        public boolean setShowAsAction(MenuItem item, int actionEnum) {
90            MenuItemCompatHoneycomb.setShowAsAction(item, actionEnum);
91            return true;
92        }
93        @Override
94        public MenuItem setActionView(MenuItem item, View view) {
95            return MenuItemCompatHoneycomb.setActionView(item, view);
96        }
97    }
98
99    /**
100     * Select the correct implementation to use for the current platform.
101     */
102    static final MenuVersionImpl IMPL;
103    static {
104        if (android.os.Build.VERSION.SDK_INT >= 11) {
105            IMPL = new HoneycombMenuVersionImpl();
106        } else {
107            IMPL = new BaseMenuVersionImpl();
108        }
109    }
110
111    // -------------------------------------------------------------------
112
113    /**
114     * Call {@link MenuItem#setShowAsAction(int) MenuItem.setShowAsAction()}.
115     * If running on a pre-{@link android.os.Build.VERSION_CODES#HONEYCOMB} device,
116     * does nothing and returns false.  Otherwise returns true.
117     */
118    public static boolean setShowAsAction(MenuItem item, int actionEnum) {
119        return IMPL.setShowAsAction(item, actionEnum);
120    }
121
122    /**
123     * Set an action view for this menu item. An action view will be displayed in place
124     * of an automatically generated menu item element in the UI when this item is shown
125     * as an action within a parent.
126     *
127     * @param view View to use for presenting this item to the user.
128     * @return This Item so additional setters can be called.
129     *
130     * @see #setShowAsAction(MenuItem, int)
131     */
132    public static MenuItem setActionView(MenuItem item, View view) {
133        return IMPL.setActionView(item, view);
134    }
135}
136