Developers / Android SDK / Configuring a StorytellerListView

Configuring a StorytellerListView

Attributes
Methods
StorytellerRowView
StorytellerGridView

Note: All of the example code snippets are using the StorytellerRowView type, however, if you are using StorytellerGridView they will work in exactly the same way.

StorytellerListView is a base abstract class for views displaying lists of Stories. The Storyteller SDK offers two implementations of this abstract class:

StorytellerRowView
StorytellerGridView

Attributes

This sections describes attributes common to StorytellerRowView and StorytellerGridView. Notes are used to mark if there is a difference in property interpretation.

StorytellerListView base class attributes:

cellType

The cellType is the style of the cell. This can either be ROUND(0) or SQUARE(1). The default value is SQUARE(1).

delegate

The delegate is the StorytellerListViewDelegate instance for StorytellerListView callbacks (see Implementing StorytellerListViewDelegate methods).

theme

The theme parameter is used to set the Theme for the StorytellerListView. If theme is set to null, then theme set asStoryteller.theme global property is used. The theme determines how the items within the List View are presented as well as various features of the player once it is launched.

uiStyle

The uiStyle adjusts whether Storyteller renders in light mode, dark mode or follows the system setting.

displayLimit

The displayLimit is the maximum amount of tiles that can be shown in the list.

uiStyle takes the following values:

StorytellerListViewStyle.AUTO - default value, the StorytellerListView will adjust its color scheme automatically according to the current system UI mode
StorytellerListViewStyle.LIGHT - force the StorytellerListView to use the light theme
StorytellerListViewStyle.DARK - force the StorytellerListView to use the dark theme

Theme

The theme used to render Story items in the list. In will also be passed to activities launched from this StoryRowView.

Example:

    val storytellerRowView = StorytellerRowView()
    val customTheme: UiTheme
    //~~~ build customized theme UITheme ~~ //
    storytellerRowView.theme = customTheme

Dynamic Scaling

Item tiles will scale dynamically to fit the row or grid view.

The base size of the tiles are:

100dp width x 150dp height for square tiles
76dp width x 105dp height for round tiles

The base size will be used when rendering the row if the dimensions of the row view cannot determine its constraints. The exact dimensions of the row view will depend on how it is defined in the layout view hierarchy, including its parents. In general, tiles will maintain its base proportion and scale up or down to meet view hierarchy constrains.

For the sake of simplicity, examples will be provided using square as 100dp/150dp = 2/3 proportions to make it easier to do calculations.

Example 1

    <com.storyteller.ui.list.StorytellerRowView
      app:cellType="square"
      android:layout_width="match_parent"
      android:layout_height="200dp"
      ...
    />

The final item tile size will be ≈ 133dp x 200dp, as 200 dp[h] * 2/3 [w/h] ≈ 133dp

Example 2

  <LinearLayout
  android:layout_width="match_parent"
  android:layout_height="200dp"
  android:orientation="vertical">
    <com.storyteller.ui.list.StorytellerRowView
      app:cellType="square"
      android:layout_width="match_parent"
      android:layout_height="match_parent"
      ...
    />
  </LinearLayout>

The final item tile size will be ≈ 133dp x 200dp. This is because the StorytellerRowView is wrapped in a parent view with a height of 200dp and has its size attributes set to match_parent. The system, therefore, expands the row view to fill the height of its parent and scales the width of the tiles accordingly.

Example 3

  <?xml version="1.0" encoding="utf-8"?>
  <com.storyteller.ui.list.StorytellerRowView
    app:cellType="square"
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="wrap_content"
    android:layout_height="match_parent"
    ...
  />

In this case, the final item tile size will be the height of the window. This happens because the StorytellerRowView is defined as the top-most view and android:layout_height="match_parent" has been set on the view. The system, therefore, expands the row view to fill the window height - and so the resulting item tiles will scale to fit the window height also.

Example 4

  ...

  <LinearLayout
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:orientation="vertical">

    <com.storyteller.ui.list.StorytellerRowView
      app:cellType="square"
      android:layout_width="match_parent"
      android:layout_height="wrap_content"
      ...
    />

    ...

  </LinearLayout>

In this case, the final item tile size will be 100dp x 150dp (the base size). Since the StorytellerRowView has been defined as the child of another view, setting android:layout_height="wrap_content" makes the item tile size 100dp x 150dp (base size).

StorytellerListViewCellType

The StorytellerListViewCellType enum can be used to set the cellType property in a StorytellerRowView

Example:

    val storytellerRow = StorytellerRowView(context)
    storytellerRowView.cellType = StorytellerListViewCellType.ROUND

XML

Attributes can also be applied in XML.

<com.storyteller.ui.list.StorytellerRowView
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:cellType="round"/>

Methods

reloadData

The reloadData method starts loading fresh data for all Stories from the API. On completion, it updates the Story data, starts prefetching content and updates the read status of the Stories. The onDataLoadStarted and onDataLoadComplete methods on the StorytellerListViewDelegate are called accordingly (the latter with appropriate data depending on the result of the API requests).

val storytellerRowView = StorytellerRowView(context)
storytellerRowView.reloadData()

StorytellerRowView

The StorytellerRowView inherits from StorytellerListView.

XML