Using the Enhanced List Screen

Now that you’ve had some time to write some BrightScript code with the recent 4.8 software release for Roku 2, Roku LT and Roku HD players, it’s time to look at some other new features in the platform.  This time around, let’s look at what’s new in the list screen component.

With the 4.8 firmware release, the list screen now supports breadcrumb text as well as mini icons for list items.  Implementing breadcrumbs in your list screens is done exactly the same way as with other supporting components:

SetBreadcrumbText(String breadcrumb1, String breadcrumb2) As Void

This can be very handy, for example, when you want to update the breadcrumb text to reflect the current selection or focus in your lists.  The event loop in your screen code can respond to the various list item events and set the breadcrumb text accordingly:

    while (true)
        msg = wait(0, port)
        if (type(msg) = "roListScreenEvent")
            if (msg.isListItemFocused())
                screen.SetBreadcrumbText("Menu", “Index “ + Stri(msg.GetIndex()))
            endif
        endif
    end while

The next new feature is the ability to add icons to your list elements.  This lets you add a bit of graphical context to each of the items in a list.  As an example, take a look at the screen shot below from the sample application included with this article:

Each of the list items has a small graphic to the right.  To add graphics like this to a list, all you need to do is specify SDSmallIconUrl and HDSmallIconUrl attributes to the list items in the content list.

    contentList = [
        {
            Title: "Breakfast",
            ID: "1",
            SDSmallIconUrl: "pkg:/images/breakfast_small.png",
            HDSmallIconUrl: "pkg:/images/breakfast_small.png",
            ShortDescriptionLine1: "Breakfast Menu",
            ShortDescriptionLine2: "Select from our award winning offerings"
        },
        ...
    ]
    list = CreateObject("roListScreen")
    list.SetContent(contentList)

In my case, I used 56×56 icons for my list items.  In reality, the images you use can be any size you like, up to the dimensions of a list item.  Using the proper size image would let you create list items that are entirely graphical instead of text.

Another feature available to you in the list screen is the ability to set the screen background image that gets displayed when a list item is focused. That’s how the pancakes in the screenshot above got rendered, for example. Although this feature is not new to the 4.8 firmware release, it is worth highlighting here since it’s not a well known list screen capability. To specify a background image for a list item, include HDBackgroundImageUrl and SDBackgroundImageUrl values.

    contentList = [
        {
            Title: "Breakfast",
            ID: "1",
            SDSmallIconUrl: "pkg:/images/breakfast_small.png",
            HDSmallIconUrl: "pkg:/images/breakfast_small.png",
            HDBackgroundImageUrl: "pkg:/images/breakfast_large.png",
            SDBackgroundImageUrl: "pkg:/images/breakfast_large.png",
            ShortDescriptionLine1: "Breakfast Menu",
            ShortDescriptionLine2: "Select from our award winning offerings"
        },
       ...
     ]

Keep in mind that the various list item attributes can be set for all list items, or for any combination of the list items in your list screens. This gives you a lot of flexibility in how you design your screens.

If you’d like to experiment more with the new list screen features, you can download the full sample application from the link below as a starting point. Good luck!
List Screen Sample

About Robert Burdick

Roku Developer Support Manager
This entry was posted in Uncategorized. Bookmark the permalink.
  • Shawk

    This is really helpful!
    One question, how do you go about linking a list item to a category?

    • Anonymous

      Hello,

      In your event loop you would add a statement like the following (inside the if type(msg) = “roListScreenEvent” clause):

      if msg.isListItemSelected()
      index = msg.GetIndex() ‘find what list item was selected
      if index = 0
      ShowNewScreenForCategoryZero()
      else if index = 1
      ShowNewScreenForCategoryOne()

      end if
      end if

      Where you define those new screen script methods.

      Cheers,
      Jon

      PS – Screen navigation/hierarchy is another great topic we’ll add a blog post on in the near future (next week or two).

    • Robert Burdick

      I just published an article on the details of screen navigation: http://blog.roku.com/developer/2012/08/09/getting-started-with-brightscript-screen-navigation/

  • deng

    How to use the left and right to deal with things?Tankyou!

  • Sonja

    Can I define the location and size of the ’roListScreen‘ by myself , just like the image below?

    • PETER

      I am sorry,