public final class

ItemAlignmentFacet

extends java.lang.Object

 java.lang.Object

↳androidx.leanback.widget.ItemAlignmentFacet

Gradle dependencies

compile group: 'androidx.leanback', name: 'leanback-grid', version: '1.0.0-alpha01'

  • groupId: androidx.leanback
  • artifactId: leanback-grid
  • version: 1.0.0-alpha01

Artifact androidx.leanback:leanback-grid:1.0.0-alpha01 it located at Google repository (https://maven.google.com/)

Androidx class mapping:

androidx.leanback.widget.ItemAlignmentFacet android.support.v17.leanback.widget.ItemAlignmentFacet

Overview

Optional facet provided by RecyclerView.Adapter or RecyclerView.ViewHolder for use in HorizontalGridView and VerticalGridView.

ItemAlignmentFacet contains single or multiple ItemAlignmentFacet.ItemAlignmentDefs. First ItemAlignmentFacet.ItemAlignmentDef describes the default alignment position for ViewHolder, it also overrides the default item alignment settings on VerticalGridView and HorizontalGridView (see BaseGridView.setItemAlignmentOffset(int) etc). One ItemAlignmentFacet can have multiple ItemAlignmentFacet.ItemAlignmentDefs, e.g. having two aligned positions when child1 gets focus or child2 gets focus. Grid view will visit focused view and its ancestors till the root of ViewHolder to match ItemAlignmentFacet.ItemAlignmentDefs' ItemAlignmentFacet.ItemAlignmentDef.getItemAlignmentFocusViewId(). Once a match found, the ItemAlignmentFacet.ItemAlignmentDef is used to calculate alignment position.

Summary

Fields
public static final floatITEM_ALIGN_OFFSET_PERCENT_DISABLED

Value indicates that percent is not used.

Constructors
publicItemAlignmentFacet()

Methods
public ItemAlignmentFacet.ItemAlignmentDefgetAlignmentDefs()

Returns read only definitions of alignment positions.

public booleanisMultiAlignment()

public voidsetAlignmentDefs(ItemAlignmentFacet.ItemAlignmentDef defs[])

Sets definitions of alignment positions.

from java.lang.Objectclone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Fields

public static final float ITEM_ALIGN_OFFSET_PERCENT_DISABLED

Value indicates that percent is not used. Equivalent to 0.

Constructors

public ItemAlignmentFacet()

Methods

public boolean isMultiAlignment()

public void setAlignmentDefs(ItemAlignmentFacet.ItemAlignmentDef defs[])

Sets definitions of alignment positions.

public ItemAlignmentFacet.ItemAlignmentDef getAlignmentDefs()

Returns read only definitions of alignment positions.

Source

/*
 * Copyright 2021 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 androidx.leanback.widget;

import android.view.View;

import androidx.annotation.NonNull;

/**
 * Optional facet provided by {@link androidx.recyclerview.widget.RecyclerView.Adapter} or
 * {@link androidx.recyclerview.widget.RecyclerView.ViewHolder} for
 * use in {@link HorizontalGridView} and {@link VerticalGridView}.
 * <p>
 * ItemAlignmentFacet contains single or multiple {@link ItemAlignmentDef}s. First
 * {@link ItemAlignmentDef} describes the default alignment position for ViewHolder, it also
 * overrides the default item alignment settings on {@link VerticalGridView} and
 * {@link HorizontalGridView} (see {@link BaseGridView#setItemAlignmentOffset(int)} etc). One
 * ItemAlignmentFacet can have multiple {@link ItemAlignmentDef}s, e.g. having two aligned positions
 * when child1 gets focus or child2 gets focus. Grid view will visit focused view and its
 * ancestors till the root of ViewHolder to match {@link ItemAlignmentDef}s'
 * {@link ItemAlignmentDef#getItemAlignmentFocusViewId()}. Once a match found, the
 * {@link ItemAlignmentDef} is used to calculate alignment position.
 */
public final class ItemAlignmentFacet {

    /**
     * Value indicates that percent is not used. Equivalent to 0.
     */
    public static final float ITEM_ALIGN_OFFSET_PERCENT_DISABLED = -1;

    /**
     * Definition of an alignment position under a view.
     */
    public static class ItemAlignmentDef {
        int mViewId = View.NO_ID;
        int mFocusViewId = View.NO_ID;
        int mOffset = 0;
        float mOffsetPercent = 50f;
        boolean mOffsetWithPadding = false;
        private boolean mAlignToBaseline;

        /**
         * Sets number of pixels to the end of low edge. Supports right to left layout direction.
         *
         * @param offset In left to right or vertical case, it's the offset added to left/top edge.
         *               In right to left case, it's the offset subtracted from right edge.
         */
        public final void setItemAlignmentOffset(int offset) {
            mOffset = offset;
        }

        /**
         * Returns number of pixels to the end of low edge. Supports right to left layout direction.
         * In left to right or vertical case, it's the offset added to left/top edge. In right to
         * left case, it's the offset subtracted from right edge.
         *
         * @return Number of pixels to the end of low edge.
         */
        public final int getItemAlignmentOffset() {
            return mOffset;
        }

        /**
         * Sets whether applies padding to item alignment when
         * {@link #getItemAlignmentOffsetPercent()} is 0 or 100.
         * <p>When true:
         * Applies start/top padding if {@link #getItemAlignmentOffsetPercent()} is 0.
         * Applies end/bottom padding if {@link #getItemAlignmentOffsetPercent()} is 100.
         * Does not apply padding if {@link #getItemAlignmentOffsetPercent()} is neither 0 nor 100.
         * </p>
         * <p>When false: does not apply padding</p>
         */
        public final void setItemAlignmentOffsetWithPadding(boolean withPadding) {
            mOffsetWithPadding = withPadding;
        }

        /**
         * Returns true if applies padding to item alignment when
         * {@link #getItemAlignmentOffsetPercent()} is 0 or 100; returns false otherwise.
         * <p>When true:
         * Applies start/top padding when {@link #getItemAlignmentOffsetPercent()} is 0.
         * Applies end/bottom padding when {@link #getItemAlignmentOffsetPercent()} is 100.
         * Does not apply padding if {@link #getItemAlignmentOffsetPercent()} is neither 0 nor 100.
         * </p>
         * <p>When false: does not apply padding</p>
         */
        public final boolean isItemAlignmentOffsetWithPadding() {
            return mOffsetWithPadding;
        }

        /**
         * Sets the offset percent for item alignment in addition to offset.  E.g., 40
         * means 40% of width/height from the low edge. In the right to left case, it's the 40%
         * width from right edge. Use {@link #ITEM_ALIGN_OFFSET_PERCENT_DISABLED} to disable.
         */
        public final void setItemAlignmentOffsetPercent(float percent) {
            if ((percent < 0 || percent > 100)
                    && percent != ITEM_ALIGN_OFFSET_PERCENT_DISABLED) {
                throw new IllegalArgumentException();
            }
            mOffsetPercent = percent;
        }

        /**
         * Gets the offset percent for item alignment in addition to offset. E.g., 40
         * means 40% of the width from the low edge. In the right to left case, it's the 40% from
         * right edge. Use {@link #ITEM_ALIGN_OFFSET_PERCENT_DISABLED} to disable.
         */
        public final float getItemAlignmentOffsetPercent() {
            return mOffsetPercent;
        }

        /**
         * Sets Id of which child view to be aligned.  View.NO_ID refers to root view and should
         * be only used in first one.  Different view ids of {@link ItemAlignmentFacet
         * #getAlignmentDefs()} define multiple alignment steps within one itemView, e.g. there are
         * two child views R.id.child1 and R.id.child2. App may allocated two
         * {@link ItemAlignmentDef}s, one with view id R.id.child1, the other with view id
         * R.id.child2. Note this id may or may not be same as the child view that takes focus.
         *
         * @param viewId The id of child view that will be aligned to.
         * @see #setItemAlignmentFocusViewId(int)
         */
        public final void setItemAlignmentViewId(int viewId) {
            mViewId = viewId;
        }

        /**
         * Returns Id of which child view to be aligned.  View.NO_ID refers to root view and should
         * be only used in first one.  Different view ids of {@link ItemAlignmentFacet
         * #getAlignmentDefs()} define multiple alignment steps within one itemView, e.g. there are
         * two child views R.id.child1 and R.id.child2. App may allocated two
         * {@link ItemAlignmentDef}s, one with view id R.id.child1, the other with view id
         * R.id.child2. Note this id may or may not be same as the child view that takes focus.
         *
         * @see #setItemAlignmentFocusViewId(int)
         */
        public final int getItemAlignmentViewId() {
            return mViewId;
        }

        /**
         * Sets Id of which child view take focus for alignment.  When not set, it will use
         * use same id of {@link #getItemAlignmentViewId()}.
         *
         * @param viewId The id of child view that will be focused to.
         */
        public final void setItemAlignmentFocusViewId(int viewId) {
            mFocusViewId = viewId;
        }

        /**
         * Returns Id of which child view take focus for alignment.  When not set, it will use
         * use same id of {@link #getItemAlignmentViewId()}
         */
        public final int getItemAlignmentFocusViewId() {
            return mFocusViewId != View.NO_ID ? mFocusViewId : mViewId;
        }

        /**
         * When true, align to {@link View#getBaseline()} for the view of with id equals
         * {@link #getItemAlignmentViewId()}; false otherwise.
         *
         * @param alignToBaseline Boolean indicating whether to align to view baseline.
         */
        public final void setAlignedToTextViewBaseline(boolean alignToBaseline) {
            this.mAlignToBaseline = alignToBaseline;
        }

        /**
         * Returns true when View should be aligned to {@link View#getBaseline()}
         */
        public boolean isAlignedToTextViewBaseLine() {
            return mAlignToBaseline;
        }
    }

    private ItemAlignmentDef[] mAlignmentDefs = new ItemAlignmentDef[]{new ItemAlignmentDef()};

    public boolean isMultiAlignment() {
        return mAlignmentDefs.length > 1;
    }

    /**
     * Sets definitions of alignment positions.
     */
    public void setAlignmentDefs(
            @SuppressWarnings("ArrayReturn") @NonNull ItemAlignmentDef[] defs) {
        if (defs == null || defs.length < 1) {
            throw new IllegalArgumentException();
        }
        mAlignmentDefs = defs;
    }

    /**
     * Returns read only definitions of alignment positions.
     */
    @SuppressWarnings("ArrayReturn")
    @NonNull
    public ItemAlignmentDef[] getAlignmentDefs() {
        return mAlignmentDefs;
    }
}