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