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