| /* |
| * Copyright (C) 2010 The Android Open Source Project |
| * |
| * Licensed under the Eclipse Public License, Version 1.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.eclipse.org/org/documents/epl-v10.php |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package com.android.ide.common.api; |
| |
| import com.android.annotations.NonNull; |
| import com.android.annotations.Nullable; |
| import com.android.utils.Pair; |
| import com.google.common.annotations.Beta; |
| |
| import java.net.URL; |
| import java.util.ArrayList; |
| import java.util.List; |
| import java.util.regex.Pattern; |
| |
| /** |
| * A {@link RuleAction} represents an action provided by an {@link IViewRule}, typically |
| * shown in a context menu or in the layout actions bar. |
| * <p/> |
| * Each action should have a reasonably unique ID. This is used when multiple nodes |
| * are selected to filter the actions down to just those actions that are supported |
| * across all selected nodes. If an action does not support multiple nodes, it can |
| * return false from {@link #supportsMultipleNodes()}. |
| * <p/> |
| * Actions can be grouped into a hierarchy of sub-menus using the {@link NestedAction} class, |
| * or into a flat submenu using the {@link Choices} class. |
| * <p/> |
| * Actions (including separators) all have a "sort priority", and this is used to |
| * sort the menu items or toolbar buttons into a specific order. |
| * <p> |
| * <b>NOTE: This is not a public or final API; if you rely on this be prepared |
| * to adjust your code for the next tools release.</b> |
| * </p> |
| */ |
| @Beta |
| public class RuleAction implements Comparable<RuleAction> { |
| /** |
| * Character used to split multiple checked choices. |
| * The pipe character "|" is used, to natively match Android resource flag separators. |
| */ |
| public static final String CHOICE_SEP = "|"; //$NON-NLS-1$ |
| |
| /** |
| * Same as {@link #CHOICE_SEP} but safe for use in regular expressions. |
| */ |
| public static final String CHOICE_SEP_PATTERN = Pattern.quote(CHOICE_SEP); |
| |
| /** |
| * The unique id of the action. |
| * @see #getId() |
| */ |
| private final String mId; |
| /** |
| * The UI-visible title of the action. |
| */ |
| private final String mTitle; |
| |
| /** A URL pointing to an icon, or null */ |
| private URL mIconUrl; |
| |
| /** |
| * A callback executed when the action is selected in the context menu. |
| */ |
| private final IMenuCallback mCallback; |
| |
| /** |
| * The sorting priority of this item; actions can be sorted according to these |
| */ |
| protected final int mSortPriority; |
| |
| /** |
| * Whether this action supports multiple nodes, see |
| * {@link #supportsMultipleNodes()} for details. |
| */ |
| private final boolean mSupportsMultipleNodes; |
| |
| /** |
| * Special value which will insert a separator in the choices' submenu. |
| */ |
| public static final String SEPARATOR = "----"; |
| |
| // Factories |
| |
| /** |
| * Constructs a new separator which will be shown in places where separators |
| * are supported such as context menus |
| * |
| * @param sortPriority a priority used for sorting this action |
| * @return a new separator |
| */ |
| @NonNull |
| public static Separator createSeparator(int sortPriority) { |
| return new Separator(sortPriority, true /* supportsMultipleNodes*/); |
| } |
| |
| /** |
| * Constructs a new base {@link RuleAction} with its ID, title and action callback. |
| * |
| * @param id The unique ID of the action. Must not be null. |
| * @param title The title of the action. Must not be null. |
| * @param callback The callback executed when the action is selected. |
| * Must not be null. |
| * @param iconUrl a URL pointing to an icon to use for this action, or null |
| * @param sortPriority a priority used for sorting this action |
| * @param supportsMultipleNodes whether this action supports multiple nodes, |
| * see {@link #supportsMultipleNodes()} for details |
| * @return the new {@link RuleAction} |
| */ |
| @NonNull |
| public static RuleAction createAction( |
| @NonNull String id, |
| @NonNull String title, |
| @NonNull IMenuCallback callback, |
| @Nullable URL iconUrl, |
| int sortPriority, |
| boolean supportsMultipleNodes) { |
| RuleAction action = new RuleAction(id, title, callback, sortPriority, |
| supportsMultipleNodes); |
| action.setIconUrl(iconUrl); |
| |
| return action; |
| } |
| |
| /** |
| * Creates a new immutable toggle action. |
| * |
| * @param id The unique id of the action. Cannot be null. |
| * @param title The UI-visible title of the context menu item. Cannot be null. |
| * @param isChecked Whether the context menu item has a check mark. |
| * @param callback A callback to execute when the context menu item is |
| * selected. |
| * @param iconUrl a URL pointing to an icon to use for this action, or null |
| * @param sortPriority a priority used for sorting this action |
| * @param supportsMultipleNodes whether this action supports multiple nodes, |
| * see {@link #supportsMultipleNodes()} for details |
| * @return the new {@link Toggle} |
| */ |
| @NonNull |
| public static Toggle createToggle( |
| @NonNull String id, |
| @NonNull String title, |
| boolean isChecked, |
| @NonNull IMenuCallback callback, |
| @Nullable URL iconUrl, |
| int sortPriority, |
| boolean supportsMultipleNodes) { |
| Toggle toggle = new Toggle(id, title, isChecked, callback, sortPriority, |
| supportsMultipleNodes); |
| toggle.setIconUrl(iconUrl); |
| return toggle; |
| } |
| |
| /** |
| * Creates a new immutable multiple-choice action with a defined ordered set |
| * of action children. |
| * |
| * @param id The unique id of the action. Cannot be null. |
| * @param title The title of the action to be displayed to the user |
| * @param provider Provides the actions to be shown as children of this |
| * action |
| * @param callback A callback to execute when the context menu item is |
| * selected. |
| * @param iconUrl the icon to use for the multiple choice action itself |
| * @param sortPriority the sorting priority to use for the multiple choice |
| * action itself |
| * @param supportsMultipleNodes whether this action supports multiple nodes, |
| * see {@link #supportsMultipleNodes()} for details |
| * @return the new {@link NestedAction} |
| */ |
| @NonNull |
| public static NestedAction createChoices( |
| @NonNull String id, |
| @NonNull String title, |
| @NonNull IMenuCallback callback, |
| @Nullable URL iconUrl, |
| int sortPriority, |
| boolean supportsMultipleNodes, |
| @NonNull ActionProvider provider) { |
| NestedAction choices = new NestedAction(id, title, provider, callback, |
| sortPriority, supportsMultipleNodes); |
| choices.setIconUrl(iconUrl); |
| return choices; |
| } |
| |
| /** |
| * Creates a new immutable multiple-choice action with a defined ordered set |
| * of children. |
| * |
| * @param id The unique id of the action. Cannot be null. |
| * @param title The title of the action to be displayed to the user |
| * @param iconUrls The icon urls for the children items (may be null) |
| * @param ids The internal ids for the children |
| * @param current The id(s) of the current choice(s) that will be check |
| * marked. Can be null. Can be an id not present in the choices |
| * map. There can be more than one id separated by |
| * {@link #CHOICE_SEP}. |
| * @param callback A callback to execute when the context menu item is |
| * selected. |
| * @param titles The UI-visible titles of the children |
| * @param iconUrl the icon to use for the multiple choice action itself |
| * @param sortPriority the sorting priority to use for the multiple choice |
| * action itself |
| * @param supportsMultipleNodes whether this action supports multiple nodes, |
| * see {@link #supportsMultipleNodes()} for details |
| * @return the new {@link Choices} |
| */ |
| @NonNull |
| public static Choices createChoices( |
| @NonNull String id, |
| @NonNull String title, |
| @NonNull IMenuCallback callback, |
| @NonNull List<String> titles, |
| @Nullable List<URL> iconUrls, |
| @NonNull List<String> ids, |
| @Nullable String current, |
| @Nullable URL iconUrl, |
| int sortPriority, |
| boolean supportsMultipleNodes) { |
| Choices choices = new Choices(id, title, callback, titles, iconUrls, |
| ids, current, sortPriority, supportsMultipleNodes); |
| choices.setIconUrl(iconUrl); |
| |
| return choices; |
| } |
| |
| /** |
| * Creates a new immutable multiple-choice action with a defined ordered set |
| * of children. |
| * |
| * @param id The unique id of the action. Cannot be null. |
| * @param title The title of the action to be displayed to the user |
| * @param iconUrls The icon urls for the children items (may be null) |
| * @param current The id(s) of the current choice(s) that will be check |
| * marked. Can be null. Can be an id not present in the choices |
| * map. There can be more than one id separated by |
| * {@link #CHOICE_SEP}. |
| * @param callback A callback to execute when the context menu item is |
| * selected. |
| * @param iconUrl the icon to use for the multiple choice action itself |
| * @param sortPriority the sorting priority to use for the multiple choice |
| * action itself |
| * @param supportsMultipleNodes whether this action supports multiple nodes, |
| * see {@link #supportsMultipleNodes()} for details |
| * @param idsAndTitles a list of pairs (of ids and titles) to use for the |
| * menu items |
| * @return the new {@link Choices} |
| */ |
| @NonNull |
| public static Choices createChoices( |
| @NonNull String id, |
| @NonNull String title, |
| @NonNull IMenuCallback callback, |
| @Nullable List<URL> iconUrls, |
| @Nullable String current, |
| @Nullable URL iconUrl, |
| int sortPriority, |
| boolean supportsMultipleNodes, |
| @NonNull List<Pair<String, String>> idsAndTitles) { |
| int itemCount = idsAndTitles.size(); |
| List<String> titles = new ArrayList<String>(itemCount); |
| List<String> ids = new ArrayList<String>(itemCount); |
| for (Pair<String, String> pair : idsAndTitles) { |
| ids.add(pair.getFirst()); |
| titles.add(pair.getSecond()); |
| } |
| Choices choices = new Choices(id, title, callback, titles, iconUrls, |
| ids, current, sortPriority, supportsMultipleNodes); |
| choices.setIconUrl(iconUrl); |
| return choices; |
| } |
| |
| /** |
| * Creates a new immutable multiple-choice action with lazily computed children. |
| * |
| * @param id The unique id of the action. Cannot be null. |
| * @param title The title of the multiple-choice itself |
| * @param callback A callback to execute when the context menu item is |
| * selected. |
| * @param provider the provider which provides choices lazily |
| * @param current The id(s) of the current choice(s) that will be check |
| * marked. Can be null. Can be an id not present in the choice |
| * alternatives. There can be more than one id separated by |
| * {@link #CHOICE_SEP}. |
| * @param iconUrl the icon to use for the multiple choice action itself |
| * @param sortPriority the sorting priority to use for the multiple choice |
| * action itself |
| * @param supportsMultipleNodes whether this action supports multiple nodes, |
| * see {@link #supportsMultipleNodes()} for details |
| * @return the new {@link Choices} |
| */ |
| @NonNull |
| public static Choices createChoices( |
| @NonNull String id, |
| @NonNull String title, |
| IMenuCallback callback, |
| @NonNull ChoiceProvider provider, |
| @Nullable String current, |
| @Nullable URL iconUrl, |
| int sortPriority, |
| boolean supportsMultipleNodes) { |
| Choices choices = new DelayedChoices(id, title, callback, |
| current, provider, sortPriority, supportsMultipleNodes); |
| choices.setIconUrl(iconUrl); |
| return choices; |
| } |
| |
| /** |
| * Creates a new {@link RuleAction} with the given id and the given title. |
| * Actions which have the same id and the same title are deemed equivalent. |
| * |
| * @param id The unique id of the action, which must be similar for all actions that |
| * perform the same task. Cannot be null. |
| * @param title The UI-visible title of the action. |
| * @param callback A callback to execute when the context menu item is |
| * selected. |
| * @param sortPriority a priority used for sorting this action |
| * @param supportsMultipleNodes the new return value for |
| * {@link #supportsMultipleNodes()} |
| */ |
| private RuleAction( |
| @NonNull String id, |
| @NonNull String title, |
| @NonNull IMenuCallback callback, |
| int sortPriority, |
| boolean supportsMultipleNodes) { |
| mId = id; |
| mTitle = title; |
| mSortPriority = sortPriority; |
| mSupportsMultipleNodes = supportsMultipleNodes; |
| mCallback = callback; |
| } |
| |
| /** |
| * Returns the unique id of the action. In the context of a multiple selection, |
| * actions which have the same id are collapsed together and must represent the same |
| * action. Cannot be null. |
| * |
| * @return the unique id of the action, never null |
| */ |
| @NonNull |
| public String getId() { |
| return mId; |
| } |
| |
| /** |
| * Returns the UI-visible title of the action, shown in the context menu. |
| * Cannot be null. |
| * |
| * @return the user name of the action, never null |
| */ |
| @NonNull |
| public String getTitle() { |
| return mTitle; |
| } |
| |
| /** |
| * Actions which have the same id and the same title are deemed equivalent. |
| */ |
| @Override |
| public boolean equals(Object obj) { |
| if (obj instanceof RuleAction) { |
| RuleAction rhs = (RuleAction) obj; |
| |
| if (mId != rhs.mId && !(mId != null && mId.equals(rhs.mId))) return false; |
| if (mTitle != rhs.mTitle && |
| !(mTitle != null && mTitle.equals(rhs.mTitle))) return false; |
| return true; |
| } |
| return false; |
| } |
| |
| /** |
| * Whether this action supports multiple nodes. An action which supports |
| * multiple nodes can be applied to different nodes by passing in different |
| * nodes to its callback. Some actions are hardcoded for a specific node (typically |
| * one that isn't selected, such as an action which affects the parent of a selected |
| * node), and these actions will not be added to the context menu when more than |
| * one node is selected. |
| * |
| * @return true if this node supports multiple nodes |
| */ |
| public boolean supportsMultipleNodes() { |
| return mSupportsMultipleNodes; |
| } |
| |
| /** |
| * Actions which have the same id and the same title have the same hash code. |
| */ |
| @Override |
| public int hashCode() { |
| int h = mId == null ? 0 : mId.hashCode(); |
| h = h ^ (mTitle == null ? 0 : mTitle.hashCode()); |
| return h; |
| } |
| |
| /** |
| * Gets a URL pointing to an icon to use for this action, if any. |
| * |
| * @return a URL pointing to an icon to use for this action, or null |
| */ |
| public URL getIconUrl() { |
| return mIconUrl; |
| } |
| |
| /** |
| * Sets a URL pointing to an icon to use for this action, if any. |
| * |
| * @param iconUrl a URL pointing to an icon to use for this action, or null |
| * @return this action, to allow setter chaining |
| */ |
| @NonNull |
| public RuleAction setIconUrl(URL iconUrl) { |
| mIconUrl = iconUrl; |
| |
| return this; |
| } |
| |
| /** |
| * Return a priority used for sorting this action |
| * |
| * @return a priority used for sorting this action |
| */ |
| public int getSortPriority() { |
| return mSortPriority; |
| } |
| |
| /** |
| * Returns the callback executed when the action is selected in the |
| * context menu. Cannot be null. |
| * |
| * @return the callback, never null |
| */ |
| @NonNull |
| public IMenuCallback getCallback() { |
| return mCallback; |
| } |
| |
| // Implements Comparable<MenuAction> |
| @Override |
| public int compareTo(RuleAction other) { |
| if (mSortPriority != other.mSortPriority) { |
| return mSortPriority - other.mSortPriority; |
| } |
| |
| return mTitle.compareTo(other.mTitle); |
| } |
| |
| @NonNull |
| @Override |
| public String toString() { |
| return "RuleAction [id=" + mId + ", title=" + mTitle + ", priority=" + mSortPriority + "]"; |
| } |
| |
| /** A separator to display between actions */ |
| public static class Separator extends RuleAction { |
| /** Construct using the factory {@link #createSeparator(int)} */ |
| private Separator(int sortPriority, boolean supportsMultipleNodes) { |
| super("_separator", "", IMenuCallback.NONE, sortPriority, //$NON-NLS-1$ //$NON-NLS-2$ |
| supportsMultipleNodes); |
| } |
| } |
| |
| /** |
| * A toggle is a simple on/off action, displayed as an item in a context menu |
| * with a check mark if the item is checked. |
| * <p/> |
| * Two toggles are equal if they have the same id, title and group-id. |
| * It is expected for the checked state and action callback to be different. |
| */ |
| public static class Toggle extends RuleAction { |
| /** |
| * True if the item is displayed with a check mark. |
| */ |
| private final boolean mIsChecked; |
| |
| /** |
| * Creates a new immutable toggle action. |
| * |
| * @param id The unique id of the action. Cannot be null. |
| * @param title The UI-visible title of the context menu item. Cannot be null. |
| * @param isChecked Whether the context menu item has a check mark. |
| * @param callback A callback to execute when the context menu item is |
| * selected. |
| */ |
| private Toggle( |
| @NonNull String id, |
| @NonNull String title, |
| boolean isChecked, |
| @NonNull IMenuCallback callback, |
| int sortPriority, |
| boolean supportsMultipleNodes) { |
| super(id, title, callback, sortPriority, supportsMultipleNodes); |
| mIsChecked = isChecked; |
| } |
| |
| /** |
| * Returns true if the item is displayed with a check mark. |
| * |
| * @return true if the item is displayed with a check mark. |
| */ |
| public boolean isChecked() { |
| return mIsChecked; |
| } |
| |
| /** |
| * Two toggles are equal if they have the same id and title. |
| * It is acceptable for the checked state and action callback to be different. |
| */ |
| @Override |
| public boolean equals(Object obj) { |
| return super.equals(obj); |
| } |
| |
| /** |
| * Two toggles have the same hash code if they have the same id and title. |
| */ |
| @Override |
| public int hashCode() { |
| return super.hashCode(); |
| } |
| } |
| |
| /** |
| * An ordered list of choices the user can choose between. For choosing between |
| * actions, there is a {@link NestedAction} class. |
| */ |
| public static class Choices extends RuleAction { |
| protected List<String> mTitles; |
| protected List<URL> mIconUrls; |
| protected List<String> mIds; |
| private boolean mRadio; |
| |
| /** |
| * One or more id for the checked choice(s) that will be check marked. |
| * Can be null. Can be an id not present in the choices map. |
| */ |
| protected final String mCurrent; |
| |
| private Choices( |
| @NonNull String id, |
| @NonNull String title, |
| @NonNull IMenuCallback callback, |
| @NonNull List<String> titles, |
| @Nullable List<URL> iconUrls, |
| @NonNull List<String> ids, |
| @Nullable String current, |
| int sortPriority, |
| boolean supportsMultipleNodes) { |
| super(id, title, callback, sortPriority, supportsMultipleNodes); |
| mTitles = titles; |
| mIconUrls = iconUrls; |
| mIds = ids; |
| mCurrent = current; |
| } |
| |
| /** |
| * Returns the list of urls to icons to display for each choice, or null |
| * |
| * @return the list of urls to icons to display for each choice, or null |
| */ |
| @Nullable |
| public List<URL> getIconUrls() { |
| return mIconUrls; |
| } |
| |
| /** |
| * Returns the list of ids for the menu choices, never null |
| * |
| * @return the list of ids for the menu choices, never null |
| */ |
| @NonNull |
| public List<String> getIds() { |
| return mIds; |
| } |
| |
| /** |
| * Returns the titles to be displayed for the menu choices, never null |
| * |
| * @return the titles to be displayed for the menu choices, never null |
| */ |
| @NonNull |
| public List<String> getTitles() { |
| return mTitles; |
| } |
| |
| /** |
| * Returns the current value of the choice |
| * |
| * @return the current value of the choice, possibly null |
| */ |
| @Nullable |
| public String getCurrent() { |
| return mCurrent; |
| } |
| |
| /** |
| * Set whether this choice list is best visualized as a radio group (instead of a |
| * dropdown) |
| * |
| * @param radio true if this choice list should be visualized as a radio group |
| */ |
| public void setRadio(boolean radio) { |
| mRadio = radio; |
| } |
| |
| /** |
| * Returns true if this choice list is best visualized as a radio group (instead |
| * of a dropdown) |
| * |
| * @return true if this choice list should be visualized as a radio group |
| */ |
| public boolean isRadio() { |
| return mRadio; |
| } |
| } |
| |
| /** |
| * An ordered list of actions the user can choose between. Similar to |
| * {@link Choices} but for actions instead. |
| */ |
| public static class NestedAction extends RuleAction { |
| /** The provider to produce the list of nested actions when needed */ |
| private final ActionProvider mProvider; |
| |
| private NestedAction( |
| @NonNull String id, |
| @NonNull String title, |
| @NonNull ActionProvider provider, |
| @NonNull IMenuCallback callback, |
| int sortPriority, |
| boolean supportsMultipleNodes) { |
| super(id, title, callback, sortPriority, supportsMultipleNodes); |
| mProvider = provider; |
| } |
| |
| /** |
| * Returns the nested actions available for the given node |
| * |
| * @param node the node to look up nested actions for |
| * @return a list of nested actions |
| */ |
| @NonNull |
| public List<RuleAction> getNestedActions(@NonNull INode node) { |
| return mProvider.getNestedActions(node); |
| } |
| } |
| |
| /** Like {@link Choices}, but the set of choices is computed lazily */ |
| private static class DelayedChoices extends Choices { |
| private final ChoiceProvider mProvider; |
| private boolean mInitialized; |
| |
| private DelayedChoices( |
| @NonNull String id, |
| @NonNull String title, |
| @NonNull IMenuCallback callback, |
| @Nullable String current, |
| @NonNull ChoiceProvider provider, |
| int sortPriority, boolean supportsMultipleNodes) { |
| super(id, title, callback, new ArrayList<String>(), new ArrayList<URL>(), |
| new ArrayList<String>(), current, sortPriority, supportsMultipleNodes); |
| mProvider = provider; |
| } |
| |
| private void ensureInitialized() { |
| if (!mInitialized) { |
| mInitialized = true; |
| mProvider.addChoices(mTitles, mIconUrls, mIds); |
| } |
| } |
| |
| @Override |
| public List<URL> getIconUrls() { |
| ensureInitialized(); |
| return mIconUrls; |
| } |
| |
| @NonNull |
| @Override |
| public List<String> getIds() { |
| ensureInitialized(); |
| return mIds; |
| } |
| |
| @NonNull |
| @Override |
| public List<String> getTitles() { |
| ensureInitialized(); |
| return mTitles; |
| } |
| } |
| |
| /** |
| * Provides the set of nested action choices associated with a {@link NestedAction} |
| * object when they are needed. Useful for lazy initialization of context |
| * menus and popup menus until they are actually needed. |
| */ |
| public interface ActionProvider { |
| /** |
| * Returns the nested actions available for the given node |
| * |
| * @param node the node to look up nested actions for |
| * @return a list of nested actions |
| */ |
| @NonNull |
| List<RuleAction> getNestedActions(@NonNull INode node); |
| } |
| |
| /** |
| * Provides the set of choices associated with an {@link Choices} |
| * object when they are needed. Useful for lazy initialization of context |
| * menus and popup menus until they are actually needed. |
| */ |
| public interface ChoiceProvider { |
| /** |
| * Adds in the needed titles, iconUrls (if any) and ids. |
| * Use {@link RuleAction#SEPARATOR} to create separators. |
| * |
| * @param titles a list of titles that the provider should append to |
| * @param iconUrls a list of icon URLs that the provider should append to |
| * @param ids a list of ids that the provider should append to |
| */ |
| void addChoices( |
| @NonNull List<String> titles, |
| @NonNull List<URL> iconUrls, |
| @NonNull List<String> ids); |
| } |
| } |
