From 1299f2b0e506950e38465b6a779e075d2aa93684 Mon Sep 17 00:00:00 2001 From: Adnan Begovic Date: Wed, 3 Jun 2015 17:38:14 -0700 Subject: [PATCH] CMSDK: Document the capabilities of ExpandedStyles for CustomTile. Change-Id: I4e609a9ad7ec17d18271334dfb087a51eb5d5bd6 --- src/java/cyanogenmod/app/CustomTile.java | 152 +++++++++++++++++++++-- 1 file changed, 144 insertions(+), 8 deletions(-) diff --git a/src/java/cyanogenmod/app/CustomTile.java b/src/java/cyanogenmod/app/CustomTile.java index 39a0f9c..8f2f4bd 100644 --- a/src/java/cyanogenmod/app/CustomTile.java +++ b/src/java/cyanogenmod/app/CustomTile.java @@ -73,6 +73,10 @@ public class CustomTile implements Parcelable { */ public int icon; + /** + * An expanded style for when the CustomTile is clicked, can either be + * a {@link GridExpandedStyle} or a {@link ListExpandedStyle} + */ public ExpandedStyle expandedStyle; /** @@ -202,12 +206,27 @@ public class CustomTile implements Parcelable { out.writeInt(icon); } + /** + * An object that can apply an expanded view style to a {@link CustomTile.Builder} + * object. + */ public static class ExpandedStyle implements Parcelable { + /** + * @hide + */ public static final int NO_STYLE = -1; + + /** + * Identifier for a grid style expanded view + */ public static final int GRID_STYLE = 0; + + /** + * Identifier for a list style expanded view + */ public static final int LIST_STYLE = 1; - public ExpandedStyle() { + private ExpandedStyle() { styleId = NO_STYLE; } @@ -221,25 +240,42 @@ public class CustomTile implements Parcelable { styleId = parcel.readInt(); } + /** + * @hide + */ public void setBuilder(Builder builder) { if (builder != null) { builder.setExpandedStyle(this); } } + /** + * @hide + */ protected void internalSetExpandedItems(ArrayList items) { expandedItems = new ExpandedItem[items.size()]; items.toArray(expandedItems); } + /** + * @hide + */ protected void internalStyleId(int id) { styleId = id; } + /** + * Retrieve the {@link ExpandedItem}s that have been set on this expanded style + * @return array of {@link ExpandedItem} + */ public ExpandedItem[] getExpandedItems() { return expandedItems; } + /** + * Retrieve the style id associated with the {@link ExpandedStyle} + * @return id for style + */ public int getStyle() { return styleId; } @@ -290,56 +326,112 @@ public class CustomTile implements Parcelable { }; } + /** + * An instance of {@link ExpandedStyle} that shows the {@link ExpandedGridItem}s in a + * non-scrollable grid. + */ public static class GridExpandedStyle extends ExpandedStyle { + /** + * Constructs a GridExpandedStyle object with default values. + */ public GridExpandedStyle() { internalStyleId(GRID_STYLE); } + /** + * Sets an {@link ArrayList} of {@link ExpandedGridItem}'s to be utilized by + * the PseudoGridView for presentation. + * @param expandedGridItems an array list of {@link ExpandedGridItem}'s + */ public void setGridItems(ArrayList expandedGridItems) { internalSetExpandedItems(expandedGridItems); } } + /** + * An instance of {@link ExpandedStyle} that shows the {@link ExpandedListItem}'s in a + * scrollable ListView. + */ public static class ListExpandedStyle extends ExpandedStyle { + /** + * Constructs a ListExpandedStyle object with default values. + */ public ListExpandedStyle() { internalStyleId(LIST_STYLE); } + /** + * Sets an {@link ArrayList} of {@link ExpandedListItem}s to be utilized by + * the ListView for presentation. + * @param expandedListItems an array list of {@link ExpandedListItem}s + */ public void setListItems(ArrayList expandedListItems) { internalSetExpandedItems(expandedListItems); } } + /** + * A container object that is utilized by {@link ExpandedStyle} to show specific items in either + * a PseudoGridView or a ListView via {@link GridExpandedStyle} and {@link ListExpandedStyle} + */ public static class ExpandedItem implements Parcelable { + /** + * A {@link PendingIntent} associated with the item. + * Triggers a {@link PendingIntent#send()} when the item is clicked. + */ public PendingIntent onClickPendingIntent; + /** + * A drawable resource id associated with the {@link ExpandedItem} + */ public int itemDrawableResourceId; + /** + * The title of the item + */ public String itemTitle; + /** + * The summary associated with the item, may be null + */ public String itemSummary = null; private ExpandedItem() { // Don't want to have this baseclass be instantiable } + /** + * @hide + */ protected void internalSetItemDrawable(int resourceId) { itemDrawableResourceId = resourceId; } + /** + * @hide + */ protected void internalSetItemSummary(String resourceId) { itemSummary = resourceId; } + /** + * @hide + */ protected void internalSetItemTitle(String title) { itemTitle = title; } + /** + * @hide + */ protected void internalSetOnClickPendingIntent(PendingIntent pendingIntent) { onClickPendingIntent = pendingIntent; } + /** + * Unflatten the ExpandedItem from a parcel. + */ protected ExpandedItem(Parcel parcel) { if (parcel.readInt() != 0) { onClickPendingIntent = PendingIntent.CREATOR.createFromParcel(parcel); @@ -398,54 +490,93 @@ public class CustomTile implements Parcelable { return b.toString(); } - @SuppressWarnings("unused") public static final Creator CREATOR = new Creator() { @Override public ExpandedItem createFromParcel(Parcel in) { - return new ExpandedItem(in); - } + return new ExpandedItem(in); + } @Override public ExpandedItem[] newArray(int size) { - return new ExpandedItem[size]; - } + return new ExpandedItem[size]; + } }; } + /** + * An instance of {@link ExpandedItem} to be utilized within a {@link GridExpandedStyle} + */ public static class ExpandedGridItem extends ExpandedItem { + /** + * Constructor for the ExpandedGridItem + */ public ExpandedGridItem() { } + /** + * Sets the title for the {@link ExpandedGridItem} + * @param title a string title + */ public void setExpandedGridItemTitle(String title) { internalSetItemTitle(title); } + /** + * Sets the {@link PendingIntent} associated with the {@link ExpandedGridItem} + * @param intent a pending intent to be triggered on click + */ public void setExpandedGridItemOnClickIntent(PendingIntent intent) { internalSetOnClickPendingIntent(intent); } + /** + * Sets the drawable resource id associated with the {@link ExpandedGridItem} + * @param resourceId a resource id that maps to a drawable + */ public void setExpandedGridItemDrawable(int resourceId) { internalSetItemDrawable(resourceId); } } + /** + * An instance of {@link ExpandedItem} to be utilized within a {@link ListExpandedStyle} + */ public static class ExpandedListItem extends ExpandedItem { + /** + * Constructor fot the ExpandedListItem + */ public ExpandedListItem() { } + /** + * Sets the title for the {@link ExpandedListItem} + * @param title a string title + */ public void setExpandedListItemTitle(String title) { internalSetItemTitle(title); } - public void setExpandedListItemSummary(String subText) { - internalSetItemSummary(subText); + /** + * Sets the title for the {@link ExpandedListItem} + * @param summary a string summary + */ + public void setExpandedListItemSummary(String summary) { + internalSetItemSummary(summary); } + /** + * Sets the {@link PendingIntent} associated with the {@link ExpandedListItem} + * @param intent a pending intent to be triggered on click + */ public void setExpandedListItemOnClickIntent(PendingIntent intent) { internalSetOnClickPendingIntent(intent); } + /** + * Sets the drawable resource id associated with the {@link ExpandedListItem} + * @param resourceId a resource id that maps to a drawable + */ public void setExpandedListItemDrawable(int resourceId) { internalSetItemDrawable(resourceId); } @@ -582,6 +713,11 @@ public class CustomTile implements Parcelable { return this; } + /** + * Set an {@link ExpandedStyle} to to be displayed when a user clicks the custom tile + * @param expandedStyle + * @return {@link cyanogenmod.app.CustomTile.Builder} + */ public Builder setExpandedStyle(ExpandedStyle expandedStyle) { if (mExpandedStyle != expandedStyle) { mExpandedStyle = expandedStyle;