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 
17 package com.android.internal.view.menu;
18 
19 import android.annotation.NonNull;
20 import android.annotation.Nullable;
21 import android.compat.annotation.UnsupportedAppUsage;
22 import android.content.Context;
23 import android.os.Parcelable;
24 import android.view.ViewGroup;
25 
26 /**
27  * A MenuPresenter is responsible for building views for a Menu object.
28  * It takes over some responsibility from the old style monolithic MenuBuilder class.
29  */
30 public interface MenuPresenter {
31     /**
32      * Called by menu implementation to notify another component of open/close events.
33      */
34     public interface Callback {
35         /**
36          * Called when a menu is closing.
37          * @param menu
38          * @param allMenusAreClosing
39          */
onCloseMenu(MenuBuilder menu, boolean allMenusAreClosing)40         public void onCloseMenu(MenuBuilder menu, boolean allMenusAreClosing);
41 
42         /**
43          * Called when a submenu opens. Useful for notifying the application
44          * of menu state so that it does not attempt to hide the action bar
45          * while a submenu is open or similar.
46          *
47          * @param subMenu Submenu currently being opened
48          * @return true if the Callback will handle presenting the submenu, false if
49          *         the presenter should attempt to do so.
50          */
51         @UnsupportedAppUsage
onOpenSubMenu(MenuBuilder subMenu)52         public boolean onOpenSubMenu(MenuBuilder subMenu);
53     }
54 
55     /**
56      * Initializes this presenter for the given context and menu.
57      * <p>
58      * This method is called by MenuBuilder when a presenter is added. See
59      * {@link MenuBuilder#addMenuPresenter(MenuPresenter)}.
60      *
61      * @param context the context for this presenter; used for view creation
62      *                and resource management, must be non-{@code null}
63      * @param menu the menu to host, or {@code null} to clear the hosted menu
64      */
initForMenu(@onNull Context context, @Nullable MenuBuilder menu)65     public void initForMenu(@NonNull Context context, @Nullable MenuBuilder menu);
66 
67     /**
68      * Retrieve a MenuView to display the menu specified in
69      * {@link #initForMenu(Context, MenuBuilder)}.
70      *
71      * @param root Intended parent of the MenuView.
72      * @return A freshly created MenuView.
73      */
getMenuView(ViewGroup root)74     public MenuView getMenuView(ViewGroup root);
75 
76     /**
77      * Update the menu UI in response to a change. Called by
78      * MenuBuilder during the normal course of operation.
79      *
80      * @param cleared true if the menu was entirely cleared
81      */
updateMenuView(boolean cleared)82     public void updateMenuView(boolean cleared);
83 
84     /**
85      * Set a callback object that will be notified of menu events
86      * related to this specific presentation.
87      * @param cb Callback that will be notified of future events
88      */
setCallback(Callback cb)89     public void setCallback(Callback cb);
90 
91     /**
92      * Called by Menu implementations to indicate that a submenu item
93      * has been selected. An active Callback should be notified, and
94      * if applicable the presenter should present the submenu.
95      *
96      * @param subMenu SubMenu being opened
97      * @return true if the the event was handled, false otherwise.
98      */
onSubMenuSelected(SubMenuBuilder subMenu)99     public boolean onSubMenuSelected(SubMenuBuilder subMenu);
100 
101     /**
102      * Called by Menu implementations to indicate that a menu or submenu is
103      * closing. Presenter implementations should close the representation
104      * of the menu indicated as necessary and notify a registered callback.
105      *
106      * @param menu the menu or submenu that is closing
107      * @param allMenusAreClosing {@code true} if all displayed menus and
108      *                           submenus are closing, {@code false} if only
109      *                           the specified menu is closing
110      */
onCloseMenu(MenuBuilder menu, boolean allMenusAreClosing)111     public void onCloseMenu(MenuBuilder menu, boolean allMenusAreClosing);
112 
113     /**
114      * Called by Menu implementations to flag items that will be shown as actions.
115      * @return true if this presenter changed the action status of any items.
116      */
flagActionItems()117     public boolean flagActionItems();
118 
119     /**
120      * Called when a menu item with a collapsable action view should expand its action view.
121      *
122      * @param menu Menu containing the item to be expanded
123      * @param item Item to be expanded
124      * @return true if this presenter expanded the action view, false otherwise.
125      */
expandItemActionView(MenuBuilder menu, MenuItemImpl item)126     public boolean expandItemActionView(MenuBuilder menu, MenuItemImpl item);
127 
128     /**
129      * Called when a menu item with a collapsable action view should collapse its action view.
130      *
131      * @param menu Menu containing the item to be collapsed
132      * @param item Item to be collapsed
133      * @return true if this presenter collapsed the action view, false otherwise.
134      */
collapseItemActionView(MenuBuilder menu, MenuItemImpl item)135     public boolean collapseItemActionView(MenuBuilder menu, MenuItemImpl item);
136 
137     /**
138      * Returns an ID for determining how to save/restore instance state.
139      * @return a valid ID value.
140      */
getId()141     public int getId();
142 
143     /**
144      * Returns a Parcelable describing the current state of the presenter.
145      * It will be passed to the {@link #onRestoreInstanceState(Parcelable)}
146      * method of the presenter sharing the same ID later.
147      * @return The saved instance state
148      */
onSaveInstanceState()149     public Parcelable onSaveInstanceState();
150 
151     /**
152      * Supplies the previously saved instance state to be restored.
153      * @param state The previously saved instance state
154      */
onRestoreInstanceState(Parcelable state)155     public void onRestoreInstanceState(Parcelable state);
156 }
157