Roku SDK Documentation : ifSpringboardScreen

Implemented By

• roSpringboardScreen

Supported Methods

Description of Methods

SetContent(content as Object) as Void

Set the content to be displayed on the Springboard Screen. The content is passed by the caller as a Content Meta-Data object describing the attributes for the title.  Internally content meta-data is stored as an roAssociativeArray.

Note that if the content type is audio (i.e, content type == audio), a progress indicator can be specified.

SetDescriptionStyle(style as String) as Void

Set the springboard style for the poster screen. Styles allow the poster screen to look differently for different types of content or different usage. The following is the list of valid screen styles:

• "audio": All tags on audio screen above are substituted with Content Meta-Data.
• "movie": All tags on the video screen above are substituted with Content Meta-Data
• "video": All tags except <Directors> and <Ratings> are on the video screen above are replaced with Content Meta-Data.
• "generic": Only the <Title> and <Description> tags on the video screen above are replaced with Content Meta-Data.

SetProgressIndicatorEnabled(enable as Boolean) as Void

Displays a progress indicator.  Note that this will only work if the content type is audio (i.e, contentType == audio).

SetProgressIndicator(progress as Integer, max as Integer) as Void

Sets the progress indicator to be progress/max complete.  max should be greater than zero, and progress should be greater than or equal to zero and less than or equal to max.

Example:

screen = CreateObject("roSpringboardScreen")        
screen.setProgressIndicatorEnabled(true)        
screen.show()      
screen.setProgressIndicator(250, 1000) ' 25 percent complete

AddButton(buttonID as Integer, title as String) as Boolean

Adds a button to the screen identified by the title and ID provided. The buttons are displayed in a standard location on the screen and appear in the order added. The ID is defined by the developer and used to uniquely identify the button instance. When the button is pressed, the script will receive an event from the application containing the ID of the button pressed and allowing the script to perform the desired action for that case.

AddThumbsUpDownButton(buttonID as Integer, thumbRating as Integer) as Boolean

Adds a button to the screen identified buttonID provided. This is just a special type of button that is displayed in the standard location on the screen and appears in the order added sequenced with other buttons. The ID is defined by the developer and used to uniquely identify the button instance. When the button is pressed, the script will receive an event from the application indicating containing the ID of the button pressed and allowing the script to perform the desired action for that case. The thumbRating takes the values of -1, 0, or 1 and corresponds to thumbs down, no rating, and thumbs up.

AddThumbsUpDownButtonWithTips(buttonID as Integer, thumbRating as Integer, tipText as Object) as Boolean

Similar to addThumbsUpDownButton().  tipText is an array of strings (size 2) which lets the script override the default tip text ["didn't like it", "liked it"].

AddRatingButton(buttonID as Integer, userRating as Integer, aggregateRating as Integer) as Boolean

Adds a star rating button to the screen. The rating is specified as an integer between 1-100 which represents the rating percentage to be displayed.  A value of 1-20 corresponds to 1 star, 21-40 corresponds to 2 stars, etc. This button is displayed in the menu area of the screen and appears in the order added. The userRating specifies the value the user rated the title, while the aggregate Rating represents the total for all users. The userRating takes precedence and determines the color of the buttons if set. The aggregateRating may display half-stars. When pressed, the button returns the userRating in the event data field.

SetStaticRatingEnabled(enable as Boolean) as Void

Sets the display of the static rating stars on or off. Defaults to enabled. When you want to use the ratings button or disable ratings on screen, set this value to false to remove this control from the screen. The extra space available will be used to display additional actors.

ClearButtons() as Void

Clears all of the buttons from the screen and resets the array of buttons back to default with no buttons set.

SetBreadcrumbText(location1 as String, location2 as String) as Void

Breadcrumbs allow the application to display a two-part navigational title which shows the current and the previous locations in the application hierarchy (e.g. TV – Friends). If both location values are set, the application will display the title in breadcrumb format. If only the first location is set, the application will display the specified text in the title area like the SetTitle API call.

SetBreadcrumbEnabled(enable as Boolean) as Void

Show or hide the breadcrumb text in the title area.

PrefetchPoster(sdPosterURL as String, hdPosterURL as String) as Void

Allows the screen to pre-fetch the poster images before the screen is displayed as a display optimization technique. This is useful when doing left-right navigation between springboard screens. The pre-fetch is done, loading the image cache and then the screen is displayed.

AllowUpdates(allow as Boolean) as Void

When adding multiple buttons to the springboard dynamically, sometimes it is desirable to defer screen updates temporarily to avoid flashing. Call AllowUpdates(false), add several buttons and then call AllowUpdates(true) to refresh the display.

CountButtons() as Integer

Returns the count of the number of buttons in the button menu on the Springboard.

AllowNavLeft(allow as Boolean) as Void

Enable or disable navigating LEFT on the springboard screen. The defautl is enabled.  When navigating is disabled, pressing LEFT will merely play a deadend sound.  When navigating is enabled, pressing LEFT will send an roSpringboardScreenEvent / isRemoteKeyPressed() event to the screen's message port.

AllowNavRight(allow as Boolean) as Void

Enable or disable navigating RIGHT on the springboard screen.  The defautl is enabled.  When navigating is disabled, pressing RIGHT will merely play a deadend sound.  When navigating is enabled, pressing RIGHT will send an roSpringboardScreenEvent / isRemoteKeyPressed() event to the screen's message port.

AllowNavRewind(allow as Boolean) as Void

Enable or disable sending the rewind remote event to script. The defautl is disabled.  When navigating is disabled, pressing REWIND will merely play a deadend sound.  When navigating is enabled, pressing LEFT will send an roSpringboardScreenEvent / isRemoteKeyPressed() event to the screen's message port.

AllowNavFastForward(allow as Boolean) as Void

Enable or disable sending the fast forward remote event to script. The defautl is disabled.  When navigating is disabled, pressing FAST FORWARD will merely play a deadend sound.  When navigating is enabled, pressing LEFT will send an roSpringboardScreenEvent / isRemoteKeyPressed() event to the screen's message port.

SetPosterStyle(style as String) as Void

Set the display style for the springboard screen. The default style is dependent on the content type of the poster, but this method enables the override of the screen type to one of the following:

• "rounded-square-generic" – Artwork sizes: SD = 143x129; HD = 209x209 Note: is non-square NTSC pixel aspect ratio images. (Default)
• "rounded-rect-16x9-generic" – 16x9 poster style. Artwork Sizes SD=177x90; HD=269x152
• "multiple-portrait-generic" – Artwork sizes: SD = 104x134 ; HD =142x202

SetAdURL(sdAdURL as String, hdAdURL as String) as Void

Set the URL of the banner Ad image to be displayed on the springboard screen. This is currently only valid for the "video" style of springboard screen. Banner Ad sizes are as follows:

• Banner Ad HD = 728x90
• Banner Ad SD = 540x60

SetAdSelectable(selectable as Boolean) as Void

Sets the banner ad to be selectable or display only. By default the banner ad is not selectable. When enabled the user can navigate and move focus to the banner image. When selected, the screen will receive an roPosterScreenEvent and the msg will return true for isAdSelected().

SetAdDisplayMode(displayMode as String) as Void

Sets the scale mode for displaying ad images. Valid display modes are:

• scale-to-fill – scale image to completely fill the rectangle of the bounding frame (default)
• scale-to-fit. – scale image to fit horizontally or vertically as appropriate while still maintaining aspect ratio. This is the preferred display mode for ads.

Show() as Boolean

Display or refresh the screen after initial creation or state changes.

Close() as Void

Close the screen and delete the associated object. Useful for avoiding screen flicker when the display order of your screens does not resemble a stack.

SetTitle(title as String) as Void

Set the title for the screen to the specified string.

UseStableFocus(enable as Boolean) as Void

When enable is true, keeps the highlighted button the same on subsequent calls to Show().  When enable is false, resets the focused button to the top button on subsequent calls to Show().  Default is false.  Generally, you will want to use the default value of false, because when navigating through springboards (using the left and right arrows) the user will want the top button to be highlighted.  Can be useful to set to true when you wish to update other dynamic text on the same screenboard and keep the highlighted button static.

SetDisplayMode(displayMode as String) as Void

Sets the mode for displaying slideshow images. This allows images to be either scaled to completely fill the screen (scale-to-fill) or scaled to fit inside the screen (scale-to-fit) while maintaining aspect ratio. Valid display modes are:

• scale-to-fill – scale image to completely fill the rectangle of the bounding frame (Default)
• scale-to-fit – scale image to fit horizontally or vertically as appropriate while still maintaining aspect ratio. Note that scale-to-fit may result in pillar-box or letter-box display of images.
• zoom-to-fill – scales and crops image to maintain aspect ratio and completely fill the rectangle of the bounding frame.

• photo-fit – Uses several methods to fit the image with a different aspect ratio to the screen. First, it will asymmetrically scale up to a maximum of 5%. Second, for landscape images, if vertical cropping is necessary, it will remove two lines off the bottom for every one line off the top up to a maximum of 30% of the image. For all images, if horizontal cropping is necessary it will crop an equal amount from both sides.