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