1/*
2 * Copyright (C) 2014 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.v7.widget;
18
19import android.content.Context;
20import android.support.annotation.AttrRes;
21import android.support.annotation.MenuRes;
22import android.support.annotation.NonNull;
23import android.support.annotation.Nullable;
24import android.support.annotation.StyleRes;
25import android.support.v7.appcompat.R;
26import android.support.v7.view.SupportMenuInflater;
27import android.support.v7.view.menu.MenuBuilder;
28import android.support.v7.view.menu.MenuPopupHelper;
29import android.support.v7.view.menu.ShowableListMenu;
30import android.view.Gravity;
31import android.view.Menu;
32import android.view.MenuInflater;
33import android.view.MenuItem;
34import android.view.View;
35import android.widget.PopupWindow;
36
37/**
38 * Static library support version of the framework's {@link android.widget.PopupMenu}.
39 * Used to write apps that run on platforms prior to Android 3.0.  When running
40 * on Android 3.0 or above, this implementation is still used; it does not try
41 * to switch to the framework's implementation. See the framework SDK
42 * documentation for a class overview.
43 */
44public class PopupMenu {
45    private final Context mContext;
46    private final MenuBuilder mMenu;
47    private final View mAnchor;
48    final MenuPopupHelper mPopup;
49
50    OnMenuItemClickListener mMenuItemClickListener;
51    OnDismissListener mOnDismissListener;
52    private View.OnTouchListener mDragListener;
53
54    /**
55     * Constructor to create a new popup menu with an anchor view.
56         *
57     * @param context Context the popup menu is running in, through which it
58     *        can access the current theme, resources, etc.
59     * @param anchor Anchor view for this popup. The popup will appear below
60     *        the anchor if there is room, or above it if there is not.
61     */
62    public PopupMenu(@NonNull Context context, @NonNull View anchor) {
63        this(context, anchor, Gravity.NO_GRAVITY);
64    }
65
66    /**
67     * Constructor to create a new popup menu with an anchor view and alignment
68     * gravity.
69     *
70     * @param context Context the popup menu is running in, through which it
71     *        can access the current theme, resources, etc.
72     * @param anchor Anchor view for this popup. The popup will appear below
73     *        the anchor if there is room, or above it if there is not.
74     * @param gravity The {@link Gravity} value for aligning the popup with its
75     *        anchor.
76     */
77    public PopupMenu(@NonNull Context context, @NonNull View anchor, int gravity) {
78        this(context, anchor, gravity, R.attr.popupMenuStyle, 0);
79    }
80
81    /**
82     * Constructor a create a new popup menu with a specific style.
83     *
84     * @param context Context the popup menu is running in, through which it
85     *        can access the current theme, resources, etc.
86     * @param anchor Anchor view for this popup. The popup will appear below
87     *        the anchor if there is room, or above it if there is not.
88     * @param gravity The {@link Gravity} value for aligning the popup with its
89     *        anchor.
90     * @param popupStyleAttr An attribute in the current theme that contains a
91     *        reference to a style resource that supplies default values for
92     *        the popup window. Can be 0 to not look for defaults.
93     * @param popupStyleRes A resource identifier of a style resource that
94     *        supplies default values for the popup window, used only if
95     *        popupStyleAttr is 0 or can not be found in the theme. Can be 0
96     *        to not look for defaults.
97     */
98    public PopupMenu(@NonNull Context context, @NonNull View anchor, int gravity,
99            @AttrRes int popupStyleAttr, @StyleRes int popupStyleRes) {
100        mContext = context;
101        mAnchor = anchor;
102
103        mMenu = new MenuBuilder(context);
104        mMenu.setCallback(new MenuBuilder.Callback() {
105            @Override
106            public boolean onMenuItemSelected(MenuBuilder menu, MenuItem item) {
107                if (mMenuItemClickListener != null) {
108                    return mMenuItemClickListener.onMenuItemClick(item);
109                }
110                return false;
111            }
112
113            @Override
114            public void onMenuModeChange(MenuBuilder menu) {
115            }
116        });
117
118        mPopup = new MenuPopupHelper(context, mMenu, anchor, false, popupStyleAttr, popupStyleRes);
119        mPopup.setGravity(gravity);
120        mPopup.setOnDismissListener(new PopupWindow.OnDismissListener() {
121            @Override
122            public void onDismiss() {
123                if (mOnDismissListener != null) {
124                    mOnDismissListener.onDismiss(PopupMenu.this);
125                }
126            }
127        });
128    }
129
130    /**
131     * Sets the gravity used to align the popup window to its anchor view.
132     * <p>
133     * If the popup is showing, calling this method will take effect only
134     * the next time the popup is shown.
135     *
136     * @param gravity the gravity used to align the popup window
137     * @see #getGravity()
138     */
139    public void setGravity(int gravity) {
140        mPopup.setGravity(gravity);
141    }
142
143    /**
144     * @return the gravity used to align the popup window to its anchor view
145     * @see #setGravity(int)
146     */
147    public int getGravity() {
148        return mPopup.getGravity();
149    }
150
151    /**
152     * Returns an {@link View.OnTouchListener} that can be added to the anchor view
153     * to implement drag-to-open behavior.
154     * <p>
155     * When the listener is set on a view, touching that view and dragging
156     * outside of its bounds will open the popup window. Lifting will select
157     * the currently touched list item.
158     * <p>
159     * Example usage:
160     * <pre>
161     * PopupMenu myPopup = new PopupMenu(context, myAnchor);
162     * myAnchor.setOnTouchListener(myPopup.getDragToOpenListener());
163     * </pre>
164     *
165     * @return a touch listener that controls drag-to-open behavior
166     */
167    @NonNull
168    public View.OnTouchListener getDragToOpenListener() {
169        if (mDragListener == null) {
170            mDragListener = new ForwardingListener(mAnchor) {
171                @Override
172                protected boolean onForwardingStarted() {
173                    show();
174                    return true;
175                }
176
177                @Override
178                protected boolean onForwardingStopped() {
179                    dismiss();
180                    return true;
181                }
182
183                @Override
184                public ShowableListMenu getPopup() {
185                    // This will be null until show() is called.
186                    return mPopup.getPopup();
187                }
188            };
189        }
190
191        return mDragListener;
192    }
193
194    /**
195     * Returns the {@link Menu} associated with this popup. Populate the
196     * returned Menu with items before calling {@link #show()}.
197     *
198     * @return the {@link Menu} associated with this popup
199     * @see #show()
200     * @see #getMenuInflater()
201     */
202    @NonNull
203    public Menu getMenu() {
204        return mMenu;
205    }
206
207    /**
208     * @return a {@link MenuInflater} that can be used to inflate menu items
209     *         from XML into the menu returned by {@link #getMenu()}
210     * @see #getMenu()
211     */
212    @NonNull
213    public MenuInflater getMenuInflater() {
214        return new SupportMenuInflater(mContext);
215    }
216
217    /**
218     * Inflate a menu resource into this PopupMenu. This is equivalent to
219     * calling {@code popupMenu.getMenuInflater().inflate(menuRes, popupMenu.getMenu())}.
220     *
221     * @param menuRes Menu resource to inflate
222     */
223    public void inflate(@MenuRes int menuRes) {
224        getMenuInflater().inflate(menuRes, mMenu);
225    }
226
227    /**
228     * Show the menu popup anchored to the view specified during construction.
229     *
230     * @see #dismiss()
231     */
232    public void show() {
233        mPopup.show();
234    }
235
236    /**
237     * Dismiss the menu popup.
238     *
239     * @see #show()
240     */
241    public void dismiss() {
242        mPopup.dismiss();
243    }
244
245    /**
246     * Sets a listener that will be notified when the user selects an item from
247     * the menu.
248     *
249     * @param listener the listener to notify
250     */
251    public void setOnMenuItemClickListener(@Nullable OnMenuItemClickListener listener) {
252        mMenuItemClickListener = listener;
253    }
254
255    /**
256     * Sets a listener that will be notified when this menu is dismissed.
257     *
258     * @param listener the listener to notify
259     */
260    public void setOnDismissListener(@Nullable OnDismissListener listener) {
261        mOnDismissListener = listener;
262    }
263
264    /**
265     * Interface responsible for receiving menu item click events if the items
266     * themselves do not have individual item click listeners.
267     */
268    public interface OnMenuItemClickListener {
269        /**
270         * This method will be invoked when a menu item is clicked if the item
271         * itself did not already handle the event.
272         *
273         * @param item the menu item that was clicked
274         * @return {@code true} if the event was handled, {@code false}
275         * otherwise
276         */
277        boolean onMenuItemClick(MenuItem item);
278    }
279
280    /**
281     * Callback interface used to notify the application that the menu has closed.
282     */
283    public interface OnDismissListener {
284        /**
285         * Called when the associated menu has been dismissed.
286         *
287         * @param menu the popup menu that was dismissed
288         */
289        void onDismiss(PopupMenu menu);
290    }
291}