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