1 // Copyright 2019 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 package org.chromium.chrome.browser.ui.appmenu;
6 
7 import android.os.Bundle;
8 import android.view.Menu;
9 import android.view.MenuItem;
10 import android.view.View;
11 
12 import androidx.annotation.Nullable;
13 
14 import java.util.List;
15 
16 /**
17  * App Menu helper that handles hiding and showing menu items based on activity state.
18  */
19 public interface AppMenuPropertiesDelegate {
20     /**
21      * Called when the containing activity is being destroyed.
22      */
destroy()23     void destroy();
24 
25     /**
26      * @return The resource id for the menu to use in {@link AppMenu}.
27      */
getAppMenuLayoutId()28     int getAppMenuLayoutId();
29 
30     /**
31      * @return A list of {@link CustomViewBinder}s to use for binding specific menu items or null if
32      *         there are no custom binders for this delegate.
33      */
34     @Nullable
getCustomViewBinders()35     List<CustomViewBinder> getCustomViewBinders();
36 
37     /**
38      * Allows the delegate to show and hide items before the App Menu is shown. It is called every
39      * time the menu is shown. This assumes that the provided menu contains all the items expected
40      * in the application menu (i.e. that the main menu has been inflated into it).
41      * @param menu Menu that will be used as the source for the App Menu pop up.
42      * @param handler The {@link AppMenuHandler} associated with {@code menu}.
43      */
prepareMenu(Menu menu, AppMenuHandler handler)44     void prepareMenu(Menu menu, AppMenuHandler handler);
45 
46     /**
47      * Gets a bundle of (optional) extra data associated with the provided MenuItem.
48      *
49      * @param item The {@link MenuItem} for which to return the Bundle.
50      * @return A {@link Bundle} for the provided MenuItem containing extra data, if any.
51      */
getBundleForMenuItem(MenuItem item)52     Bundle getBundleForMenuItem(MenuItem item);
53 
54     /**
55      * Notify the delegate that the load state changed.
56      * @param isLoading Whether the page is currently loading.
57      */
loadingStateChanged(boolean isLoading)58     void loadingStateChanged(boolean isLoading);
59 
60     /**
61      * Notify the delegate that menu was dismissed.
62      */
onMenuDismissed()63     void onMenuDismissed();
64 
65     /**
66      * @return Resource layout id for the footer if there should be one. O otherwise. The footer
67      *         is shown at a fixed position at the bottom the app menu. It is always visible and
68      *         overlays other app menu items if necessary.
69      */
getFooterResourceId()70     int getFooterResourceId();
71 
72     /**
73      * @return The resource ID for a layout the be used as the app menu header if there should be
74      *         one. 0 otherwise. The header will be displayed as the first item in the app menu. It
75      *         will be scrolled off as the menu scrolls.
76      */
getHeaderResourceId()77     int getHeaderResourceId();
78 
79     /**
80      * @return The resource ID for a layout the be used as the app menu divider. The divider will be
81      *         displayed as a line between menu item groups.
82      */
getGroupDividerId()83     int getGroupDividerId();
84 
85     /**
86      * Determines whether the footer should be shown based on the maximum available menu height.
87      * @param maxMenuHeight The maximum available height for the menu to draw.
88      * @return Whether the footer, as specified in {@link #getFooterResourceId()}, should be shown.
89      */
shouldShowFooter(int maxMenuHeight)90     boolean shouldShowFooter(int maxMenuHeight);
91 
92     /**
93      * Determines whether the header should be shown based on the maximum available menu height.
94      * @param maxMenuHeight The maximum available height for the menu to draw.
95      * @return Whether the header, as specified in {@link #getHeaderResourceId()}, should be shown.
96      */
shouldShowHeader(int maxMenuHeight)97     boolean shouldShowHeader(int maxMenuHeight);
98 
99     /**
100      * A notification that the footer view has finished inflating.
101      * @param appMenuHandler The handler for the menu the view is inside of.
102      * @param view The view that was inflated.
103      */
onFooterViewInflated(AppMenuHandler appMenuHandler, View view)104     void onFooterViewInflated(AppMenuHandler appMenuHandler, View view);
105 
106     /**
107      * A notification that the header view has finished inflating.
108      * @param appMenuHandler The handler for the menu the view is inside of.
109      * @param view The view that was inflated.
110      */
onHeaderViewInflated(AppMenuHandler appMenuHandler, View view)111     void onHeaderViewInflated(AppMenuHandler appMenuHandler, View view);
112 
113     /**
114      * @return For items with both a text label and a non-interactive icon, whether the app menu
115      *         should show the icon before the text.
116      */
shouldShowIconBeforeItem()117     boolean shouldShowIconBeforeItem();
118 
119     /**
120      * Record the user selections if users make selected similar MenuItems.
121      *
122      * @param previousMenuItemId The previous selected MenuItem Id.
123      * @param currentMenuItemId The current selected MenuItem Id.
124      * @return Whether the pattern is recorded.
125      */
recordAppMenuSimilarSelectionIfNeeded(int previousMenuItemId, int currentMenuItemId)126     boolean recordAppMenuSimilarSelectionIfNeeded(int previousMenuItemId, int currentMenuItemId);
127 }
128