Determining whether to display home screen or full screen

A widget enabled for the home screen has two views, home screen view and a full screen view. You must implement a function in your widget that determines in which view to display the widget and call that function in response to communication from the home screen.

The home screen communicates with the widget when users interact with the home screen. Communication between the home screen and the widget occurs at the system level, so it happens automatically. When the widget receives communication from the home screen, it fires the following events:

  • onload() and onshow() when users add a widget to the home screen.

  • onshow() and onresize() when the mobile device user selects a home screen widget to launch it in full view.

  • onshow() and onresize() when the home screen moves from the background to the foreground.

For more information, see Communication between the home screen and WRT.

To determine which view to display

  1. Write JavaScript code that determines the current screen size and uses that value to initialize either the home screen view or the full screen view.

    For example, the following functions set a threshold value of 150 pixels to determine whether to display the widget in full screen view (initFull) or home screen view (initHomeScreen).

    function setViewMode(){
       var isInHSView = isHSViewMode();
    	
       if ( isInHSView ) {
           initHomeScreen();
    		   
    	 } else {
          initFull();
       }
    }
    
    function isHSViewMode() {
    	   var screenHeight = window.innerheight;
    	   return ( screenHeight < HS_VIEW_THRESHOLD );
    }	
    
    
    HS_VIEW_TRESHOLD = 150;
    
  2. Call the setViewMode() function in response to onload(), onshow(), and onresize() events.

    For example, the following HTML code calls setViewMode() in response to these events.

    <body id="body" onload="setViewMode();" onshow="setViewMode();" onresize="setViewMode();">

This is a simplified version of the code to illustrate the basic functionality. For a more real-world example, see Enabling STEW for the home screen.