xref: /frameworks/support/v17/leanback/src/android/support/v17/leanback/widget/GuidedAction.java

/*
 * Copyright (C) 2015 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.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.apache.org/licenses/LICENSE-2.0
 *
 * 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 android.support.v17.leanback.widget;

import android.content.Context;
import android.content.Intent;
import android.graphics.drawable.Drawable;
import android.util.Log;

/**
 * A data class which represents an action within a {@link
 * android.support.v17.leanback.app.GuidedStepFragment}. GuidedActions contain at minimum a title
 * and a description, and typically also an icon.
 * <p>
 * A GuidedAction typically represents a single action a user may take, but may also represent a
 * possible choice out of a group of mutually exclusive choices (similar to radio buttons), or an
 * information-only label (in which case the item cannot be clicked).
 * <p>
 * GuidedActions may optionally be checked. They may also indicate that they will request further
 * user input on selection, in which case they will be displayed with a chevron indicator.
 */
public class GuidedAction extends Action {

    private static final String TAG = "GuidedAction";

    public static final int NO_DRAWABLE = 0;
    public static final int NO_CHECK_SET = 0;
    public static final int DEFAULT_CHECK_SET_ID = 1;

    /**
     * Builds a {@link GuidedAction} object.
     */
    public static class Builder {
        private long mId;
        private String mTitle;
        private String mDescription;
        private Drawable mIcon;
        private boolean mChecked;
        private boolean mMultilineDescription;
        private boolean mHasNext;
        private boolean mInfoOnly;
        private int mCheckSetId = NO_CHECK_SET;
        private boolean mEnabled = true;
        private Intent mIntent;

        /**
         * Builds the GuidedAction corresponding to this Builder.
         * @return the GuidedAction as configured through this Builder.
         */
        public GuidedAction build() {
            GuidedAction action = new GuidedAction();
            // Base Action values
            action.setId(mId);
            action.setLabel1(mTitle);
            action.setLabel2(mDescription);
            action.setIcon(mIcon);

            // Subclass values
            action.mIntent = mIntent;
            action.mChecked = mChecked;
            action.mCheckSetId = mCheckSetId;
            action.mMultilineDescription = mMultilineDescription;
            action.mHasNext = mHasNext;
            action.mInfoOnly = mInfoOnly;
            action.mEnabled = mEnabled;
            return action;
        }

        /**
         * Sets the ID associated with this action.  The ID can be any value the client wishes;
         * it is typically used to determine what to do when an action is clicked.
         * @param id The ID to associate with this action.
         */
        public Builder id(long id) {
            mId = id;
            return this;
        }

        /**
         * Sets the title for this action.  The title is typically a short string indicating the
         * action to be taken on click, e.g. "Continue" or "Cancel".
         * @param title The title for this action.
         */
        public Builder title(String title) {
            mTitle = title;
            return this;
        }

        /**
         * Sets the description for this action.  The description is typically a longer string
         * providing extra information on what the action will do.
         * @param description The description for this action.
         */
        public Builder description(String description) {
            mDescription = description;
            return this;
        }

        /**
         * Sets the intent associated with this action.  Clients would typically fire this intent
         * directly when the action is clicked.
         * @param intent The intent associated with this action.
         */
        public Builder intent(Intent intent) {
            mIntent = intent;
            return this;
        }

        /**
         * Sets the action's icon drawable.
         * @param icon The drawable for the icon associated with this action.
         */
        public Builder icon(Drawable icon) {
            mIcon = icon;
            return this;
        }

        /**
         * Sets the action's icon drawable by retrieving it by resource ID from the specified
         * context. This is a convenience function that simply looks up the drawable and calls
         * {@link #icon}.
         * @param iconResourceId The resource ID for the icon associated with this action.
         * @param context The context whose resource ID should be retrieved.
         */
        public Builder iconResourceId(int iconResourceId, Context context) {
            return icon(context.getResources().getDrawable(iconResourceId));
        }

        /**
         * Indicates whether this action is initially checked.
         * @param checked Whether this action is checked.
         */
        public Builder checked(boolean checked) {
            mChecked = checked;
            return this;
        }

        /**
         * Indicates whether this action is part of a single-select group similar to radio buttons.
         * When one item in a check set is checked, all others with the same check set ID will be
         * unchecked automatically.
         * @param checkSetId The check set ID, or {@link #NO_CHECK_SET) to indicate no check set.
         */
        public Builder checkSetId(int checkSetId) {
            mCheckSetId = checkSetId;
            return this;
        }

        /**
         * Indicates whether the title and description are long, and should be displayed
         * appropriately.
         * @param multilineDescription Whether this action has a multiline description.
         */
        public Builder multilineDescription(boolean multilineDescription) {
            mMultilineDescription = multilineDescription;
            return this;
        }

        /**
         * Indicates whether this action has a next state and should display a chevron.
         * @param hasNext Whether this action has a next state.
         */
        public Builder hasNext(boolean hasNext) {
            mHasNext = hasNext;
            return this;
        }

        /**
         * Indicates whether this action is for information purposes only and cannot be clicked.
         * @param infoOnly Whether this action has a next state.
         */
        public Builder infoOnly(boolean infoOnly) {
            mInfoOnly = infoOnly;
            return this;
        }

        /**
         * Indicates whether this action is enabled.  If not enabled, an action cannot be clicked.
         * @param enabled Whether the action is enabled.
         */
        public Builder enabled(boolean enabled) {
            mEnabled = enabled;
            return this;
        }
    }

    private boolean mChecked;
    private boolean mMultilineDescription;
    private boolean mHasNext;
    private boolean mInfoOnly;
    private int mCheckSetId;
    private boolean mEnabled;

    private Intent mIntent;

    private GuidedAction() {
        super(0);
    }

    /**
     * Returns the title of this action.
     * @return The title set when this action was built.
     */
    public CharSequence getTitle() {
        return getLabel1();
    }

    /**
     * Returns the description of this action.
     * @return The description set when this action was built.
     */
    public CharSequence getDescription() {
        return getLabel2();
    }

    /**
     * Returns the intent associated with this action.
     * @return The intent set when this action was built.
     */
    public Intent getIntent() {
        return mIntent;
    }

    /**
     * Returns whether this action is checked.
     * @return true if the action is currently checked, false otherwise.
     */
    public boolean isChecked() {
        return mChecked;
    }

    /**
     * Sets whether this action is checked.
     * @param checked Whether this action should be checked.
     */
    public void setChecked(boolean checked) {
        mChecked = checked;
    }

    /**
     * Returns the check set id this action is a part of. All actions in the
     * same list with the same check set id are considered linked. When one
     * of the actions within that set is selected, that action becomes
     * checked, while all the other actions become unchecked.
     *
     * @return an integer representing the check set this action is a part of, or
     *         {@link #NO_CHECK_SET} if this action isn't a part of a check set.
     */
    public int getCheckSetId() {
        return mCheckSetId;
    }

    /**
     * Returns whether this action is has a multiline description.
     * @return true if the action was constructed as having a multiline description, false
     * otherwise.
     */
    public boolean hasMultilineDescription() {
        return mMultilineDescription;
    }

    /**
     * Returns whether this action is enabled.
     * @return true if the action is currently enabled, false otherwise.
     */
    public boolean isEnabled() {
        return mEnabled;
    }

    /**
     * Sets whether this action is enabled.
     * @param enabled Whether this action should be enabled.
     */
    public void setEnabled(boolean enabled) {
        mEnabled = enabled;
    }

    /**
     * Returns whether this action will request further user input when selected, such as showing
     * another GuidedStepFragment or launching a new activity. Configured during construction.
     * @return true if the action will request further user input when selected, false otherwise.
     */
    public boolean hasNext() {
        return mHasNext;
    }

    /**
     * Returns whether the action will only display information and is thus not clickable. If both
     * this and {@link #hasNext()} are true, infoOnly takes precedence. The default is false. For
     * example, this might represent e.g. the amount of storage a document uses, or the cost of an
     * app.
     * @return true if will only display information, false otherwise.
     */
    public boolean infoOnly() {
        return mInfoOnly;
    }

}