130837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell/* 26e6abe6eb358db4c3932752249c8ac61dd3dab21Jeff Brown * Copyright (C) 2013 The Android Open Source Project 330837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * 430837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * Licensed under the Apache License, Version 2.0 (the "License"); 530837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * you may not use this file except in compliance with the License. 630837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * You may obtain a copy of the License at 730837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * 830837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * http://www.apache.org/licenses/LICENSE-2.0 930837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * 1030837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * Unless required by applicable law or agreed to in writing, software 1130837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * distributed under the License is distributed on an "AS IS" BASIS, 1230837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 1330837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * See the License for the specific language governing permissions and 1430837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * limitations under the License. 1530837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell */ 1630837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell 1730837f1095c803f332f4a1c3f0917c8afdd50156Adam Powellpackage android.support.v4.internal.view; 1830837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell 1930837f1095c803f332f4a1c3f0917c8afdd50156Adam Powellimport android.support.v4.view.ActionProvider; 2030837f1095c803f332f4a1c3f0917c8afdd50156Adam Powellimport android.support.v4.view.MenuItemCompat; 2130837f1095c803f332f4a1c3f0917c8afdd50156Adam Powellimport android.view.MenuItem; 2230837f1095c803f332f4a1c3f0917c8afdd50156Adam Powellimport android.view.View; 2330837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell 2430837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell/** 2530837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * Interface for direct access to a previously created menu item. 2630837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * 2779c1dba5b509ae3e7c867827949d8fdfd37e8f52Chris Banes * This version extends the one available in the framework to ensures that any necessary 2879c1dba5b509ae3e7c867827949d8fdfd37e8f52Chris Banes * elements added in later versions of the framework, are available for all platforms. 2930837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * 3079c1dba5b509ae3e7c867827949d8fdfd37e8f52Chris Banes * @see android.view.MenuItem 3179c1dba5b509ae3e7c867827949d8fdfd37e8f52Chris Banes * @hide 3230837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell */ 3330837f1095c803f332f4a1c3f0917c8afdd50156Adam Powellpublic interface SupportMenuItem extends android.view.MenuItem { 3430837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell /* 3530837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * These should be kept in sync with attrs.xml enum constants for showAsAction 3630837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell */ 3730837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell /** 3830837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * Never show this item as a button in an Action Bar. 3930837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell */ 4030837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell public static final int SHOW_AS_ACTION_NEVER = 0; 4130837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell /** 4230837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * Show this item as a button in an Action Bar if the system decides there is room for it. 4330837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell */ 4430837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell public static final int SHOW_AS_ACTION_IF_ROOM = 1; 4530837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell /** 4630837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * Always show this item as a button in an Action Bar. 4730837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * Use sparingly! If too many items are set to always show in the Action Bar it can 4830837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * crowd the Action Bar and degrade the user experience on devices with smaller screens. 4930837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * A good rule of thumb is to have no more than 2 items set to always show at a time. 5030837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell */ 5130837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell public static final int SHOW_AS_ACTION_ALWAYS = 2; 5230837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell 5330837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell /** 5430837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * When this item is in the action bar, always show it with a text label even if it also has an 5530837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * icon specified. 5630837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell */ 5730837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell public static final int SHOW_AS_ACTION_WITH_TEXT = 4; 5830837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell 5930837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell /** 6030837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * This item's action view collapses to a normal menu item. When expanded, the action view 6130837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * temporarily takes over a larger segment of its container. 6230837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell */ 6330837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell public static final int SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW = 8; 6430837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell 6530837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell /** 6630837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * Sets how this item should display in the presence of an Action Bar. The parameter actionEnum 6730837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * is a flag set. One of {@link #SHOW_AS_ACTION_ALWAYS}, {@link #SHOW_AS_ACTION_IF_ROOM}, or 6830837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * {@link #SHOW_AS_ACTION_NEVER} should be used, and you may optionally OR the value with {@link 6930837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * #SHOW_AS_ACTION_WITH_TEXT}. SHOW_AS_ACTION_WITH_TEXT requests that when the item is shown as 7030837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * an action, it should be shown with a text label. 7130837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * 7230837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @param actionEnum How the item should display. One of {@link #SHOW_AS_ACTION_ALWAYS}, {@link 7330837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * #SHOW_AS_ACTION_IF_ROOM}, or {@link #SHOW_AS_ACTION_NEVER}. 7430837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * SHOW_AS_ACTION_NEVER is the default. 7530837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @see android.app.ActionBar 7630837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @see #setActionView(View) 7730837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell */ 7830837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell public void setShowAsAction(int actionEnum); 7930837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell 8030837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell /** 8130837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * Sets how this item should display in the presence of an Action Bar. 8230837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * The parameter actionEnum is a flag set. One of {@link #SHOW_AS_ACTION_ALWAYS}, 8330837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * {@link #SHOW_AS_ACTION_IF_ROOM}, or {@link #SHOW_AS_ACTION_NEVER} should 8430837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * be used, and you may optionally OR the value with {@link #SHOW_AS_ACTION_WITH_TEXT}. 8530837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * SHOW_AS_ACTION_WITH_TEXT requests that when the item is shown as an action, 8630837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * it should be shown with a text label. 8730837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * 8830837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * <p>Note: This method differs from {@link #setShowAsAction(int)} only in that it 8930837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * returns the current MenuItem instance for call chaining. 9030837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * 9130837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @param actionEnum How the item should display. One of {@link #SHOW_AS_ACTION_ALWAYS}, {@link 9230837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * #SHOW_AS_ACTION_IF_ROOM}, or {@link #SHOW_AS_ACTION_NEVER}. 9330837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * SHOW_AS_ACTION_NEVER is the default. 9430837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @return This MenuItem instance for call chaining. 9530837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @see android.app.ActionBar 9630837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @see #setActionView(View) 9730837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell */ 9830837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell public MenuItem setShowAsActionFlags(int actionEnum); 9930837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell 10030837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell /** 10130837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * Set an action view for this menu item. An action view will be displayed in place 10230837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * of an automatically generated menu item element in the UI when this item is shown 10330837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * as an action within a parent. 10430837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * 10530837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * <p><strong>Note:</strong> Setting an action view overrides the action provider 10630837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * provider set via {@link #setSupportActionProvider(android.support.v4.view.ActionProvider)}. </p> 10730837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * 10830837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @param view View to use for presenting this item to the user. 10930837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @return This Item so additional setters can be called. 11030837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @see #setShowAsAction(int) 11130837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell */ 11230837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell public MenuItem setActionView(View view); 11330837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell 11430837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell /** 11530837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * Set an action view for this menu item. An action view will be displayed in place 11630837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * of an automatically generated menu item element in the UI when this item is shown 11730837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * as an action within a parent. 11830837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * 11930837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * <p><strong>Note:</strong> Setting an action view overrides the action provider 12030837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * provider set via {@link #setSupportActionProvider(android.support.v4.view.ActionProvider)}. </p> 12130837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * 12230837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @param resId Layout resource to use for presenting this item to the user. 12330837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @return This Item so additional setters can be called. 12430837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @see #setShowAsAction(int) 12530837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell */ 12630837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell public MenuItem setActionView(int resId); 12730837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell 12830837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell /** 12930837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * Returns the currently set action view for this menu item. 13030837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * 13130837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @return This item's action view 13230837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @see #setActionView(View) 13330837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @see #setShowAsAction(int) 13430837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell */ 13530837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell public View getActionView(); 13630837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell 13730837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell /** 13830837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * Sets the {@link android.support.v4.view.ActionProvider} responsible for creating an action view if 13930837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * the item is placed on the action bar. The provider also provides a default 14030837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * action invoked if the item is placed in the overflow menu. 14130837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * 14230837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * <p><strong>Note:</strong> Setting an action provider overrides the action view 14330837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * set via {@link #setActionView(int)} or {@link #setActionView(View)}. 14430837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * </p> 14530837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * 14630837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @param actionProvider The action provider. 14730837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @return This Item so additional setters can be called. 14830837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @see android.support.v4.view.ActionProvider 14930837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell */ 15030837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell public SupportMenuItem setSupportActionProvider(ActionProvider actionProvider); 15130837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell 15230837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell /** 15330837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * Gets the {@link ActionProvider}. 15430837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * 15530837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @return The action provider. 15630837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @see ActionProvider 15730837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @see #setSupportActionProvider(ActionProvider) 15830837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell */ 15930837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell public ActionProvider getSupportActionProvider(); 16030837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell 16130837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell /** 16230837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * Expand the action view associated with this menu item. The menu item must have an action view 16330837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * set, as well as the showAsAction flag {@link #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW}. If a 16430837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * listener has been set using {@link #setSupportOnActionExpandListener(android.support.v4.view.MenuItemCompat.OnActionExpandListener)} 16530837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * it will have its {@link android.support.v4.view.MenuItemCompat.OnActionExpandListener#onMenuItemActionExpand(MenuItem)} method 16630837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * invoked. The listener may return false from this method to prevent expanding the action view. 16730837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * 16830837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @return true if the action view was expanded, false otherwise. 16930837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell */ 17030837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell public boolean expandActionView(); 17130837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell 17230837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell /** 17330837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * Collapse the action view associated with this menu item. The menu item must have an action 17430837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * view set, as well as the showAsAction flag {@link #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW}. If a 17530837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * listener has been set using {@link #setSupportOnActionExpandListener(android.support.v4.view.MenuItemCompat.OnActionExpandListener)} 17630837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * it will have its {@link android.support.v4.view.MenuItemCompat.OnActionExpandListener#onMenuItemActionCollapse(MenuItem)} method 17730837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * invoked. The listener may return false from this method to prevent collapsing the action 17830837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * view. 17930837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * 18030837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @return true if the action view was collapsed, false otherwise. 18130837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell */ 18230837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell public boolean collapseActionView(); 18330837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell 18430837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell /** 18530837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * Returns true if this menu item's action view has been expanded. 18630837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * 18730837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @return true if the item's action view is expanded, false otherwise. 18830837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @see #expandActionView() 18930837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @see #collapseActionView() 19030837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @see #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW 19130837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @see android.support.v4.view.MenuItemCompat.OnActionExpandListener 19230837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell */ 19330837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell public boolean isActionViewExpanded(); 19430837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell 19530837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell /** 19630837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * Set an {@link android.support.v4.view.MenuItemCompat.OnActionExpandListener} on this menu item to be notified when the associated 19730837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * action view is expanded or collapsed. The menu item must be configured to expand or collapse 19830837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * its action view using the flag {@link #SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW}. 19930837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * 20030837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @param listener Listener that will respond to expand/collapse events 20130837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell * @return This menu item instance for call chaining 20230837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell */ 20330837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell public SupportMenuItem setSupportOnActionExpandListener(MenuItemCompat.OnActionExpandListener listener); 20430837f1095c803f332f4a1c3f0917c8afdd50156Adam Powell}