scalability guidelines (Tiny version)

Warning:
This tutorial covers only Tiny Mobile Widgets versions.
On Mobile Widgets, use scalability guidelines for Mobile Widgets.

Working on mobile phones leads to work on different screen sizes.
It would be heavy and restrictive to develop one application per screen resolution. So we have introduced the scalability feature into Tiny Mobile Widgets.
Developers write the application code once and for all. Helped by using a Message node all VRML scenes can be aware of the size of the screen and calculate size and positions of graphical elements. And even better : it is a "screen size changed" Message.
So that VRML scenes are aware of the screen size and also WHEN screen size changed (dynamic). This last ability is useful on mobile phones that can switch from portrait to landscape mode.

Avoid calculations

Keep in mind this project targets low-end devices. Please limit size and position calculations to the bare essentials.
You can add filter TRUE to each ImageTexture node which is bad rendered.
But use it sparingly because it generates a lots of calculations in memory.

Default values

Our reference size is 128*128 or 128*176 (in pixels). It is called "the 128-mode" afterwards.
128 mode devices are often those whith the worse CPU. So it is important to avoid useless calculations, that's why default sizes and translations are set for 128 mode. Calculations should be done only to manage other screen size.

Size informations storage

How does widget know the screen size? the size of the area where they can display ? The screen size can be accessed by the Browser javascript API, method Browser.getWidth() and Browser.getHeight().
The widget size is stored into cookies: Browser.getIntCooky('widgetWidth') and Browser.getIntCooky('widgetHeight').
The following cooky can also be useful to position the widget icon into the title bar: Browser.getIntCooky('iconSize').
Each widget has to position its icon, the system doesn't do that.
All these informations are automatically set by the system.

Size Changed event

The system can notify each VRML scene that the size changed (switch from portait to landscape mode for example). Therefore, the VRML scene has to contain the following Message node:

DEF SIZE_CHANGED Message {
    url "MEMOPLAYER"
}

This node listen to the "MEMOPLAYER" channel. You have to add a link message reception to a script function that does calculations. This link is done by the following ROUTE: (by convention, ROUTE are put at the end of the VRML scene)

ROUTE SIZE_CHANGED.data_changed TO SCRIPT.sizeHandler

Now, just add a new entry to the script in your VRML scene:

 function sizeHandler () {
   if (sizeHandler[0] == 'SIZE_CHANGED') { //check if notification is "SIZE_CHANGED". In fact channel "MEMOPLAYER" is also used for other type of notification
     updateScreenSize ();
    }
 }
 function updateScreenSize() {
  //some size calculations
 }

Two calculation modes

To avoid useless calculations, we decided to have two calculation modes:

screen width > 128 pixels: you have to do size and position calculations. Put them into updateScreenSize method, inside the if(Browser.width() > 128) to do this calculations only if necessary. You should limit calculations to the bare essentials.
screen width == 128 pixels: no calculations needed because default values are used for sizes and translations. Because we support 128*128 and 128*176 screen size in this mode, you may need some calculation depending on height. Put them into updateScreenSize method, outside the if(Browser.width() > 128)

Who does what?

First, identify both following cases:

the size of the graphical element is in parameter because the graphical element is skinable. For example a list can take all the area available for widget or a smaller area if the window is composed of a list element and another element. You don't do scalability but skins.
the size of the graphical element is constant, do not need to be in parameter : it will always be the same percentage of the screen size/widget size. You just need to be notified of the size change. For example carousel will always take the whole area available for widgets. You do scalability.

If a prototype displays one (or more) graphical element(s) depending on the screen size, the position of the element in the screen must be set by its parent (the scene calling the prototype, has a Transform2D node node with a translation one step over the prototype node).
If the parent need the children's size to position it:

the children has to put its size into an exposedField (to be accessed by the parent).
the parent's notification Message (SizeNotifier / Message) must happen after the children's notification =Message= i.e. the Message Node (or SizeNotifier) must stand AFTER the children nodes into the parent scene.

Aspect ratio for images

To avoid ugly stretches on images, don't forget to respect their aspect ratio. The image ratio is: imageWidth / imageHeight and vice versa. When you do scalability, you should calculate imageWidth or imageHeight and found the other helped by the ratio. It will keep the real aspect of the image. If it is bad rendered, you can use attribut filter TRUE inside the ImageTexture node. But filter uses a lot of CPU.

To support landscape and portrait mode, sometimes you will have to use the minimum between screen width and height to be sure that the scalable area fit with the real screen size.

       DEF SIZE_CHANGED Message { url "MEMOPLAYER" }

       #Part of code of carousel screen
       DEF BANNER_TRS Transform2D {
            translation 0 -46
            children [
                Shape {
                    appearance Appearance {
                        texture ImageTexture { url "banner.png" }
                    }
                    geometry DEF BANNER_REC Rectangle { size 128 40 }
                }
                DEF APPTITLE_TICKER Ticker {
                    speed 1
                    size 100 36
                    translation 0 8
                    textColor 0.2 0.2 0.2
                    fontStyle FontStyle { size 12 justify ["MIDDLE" "MIDDLE"] }
                }

            # the left arrow
            DEF LA_TRS Transform2D {
                    translation -59 0
                    children [
                        Shape {
                            appearance Appearance {
                                texture DEF LA_TEX ImageTexture { filter TRUE url ["leftArrowOff.png" "leftArrowOff.png" "leftArrowOn.png" ] }
                            }
                            geometry DEF ARROW_REC Rectangle { size 6 10 }
                        }
                    ]
                }
                # the right arrow
                DEF RA_TRS Transform2D {
                    translation 59 0
                    children [
                        Shape {
                            appearance Appearance {
                                texture DEF RA_TEX ImageTexture { filter TRUE url ["rightArrowOff.png" "rightArrowOff.png" "rightArrowOn.png" ] }
                            }
                            geometry USE ARROW_REC
                        }
                    ]
                }
             ]
         }

DEF SCRIPT Script {
   eventIn MFString sizeHandler
   field SFNode laTex USE LA_TEX
   field SFNode laTrs USE LA_TRS
   field SFNode raTex USE RA_TEX
   field SFNode raTrs USE RA_TRS
   field SFNode bannerTrs USE BANNER_TRS
   field SFNode bannerRec USE BANNER_REC
   field SFVec2f screenSize 0 0
   field SFInt32 margin 2
   field SFInt32 posX 0 #global variable to be calculate into updateScreenSize and re-used in other functions of the script
   ...
   url "javascript:
            function initialize () {
                updateScreenSize ();
                loadWidgetsList ();
                if (currentItem == -1) { currentItem = 0; }
                else if (currentItem == -2) { currentItem = nbItems-1; }
                Browser.sendMessage ('Board', 'INIT', loc.Title, loc.Menu, loc.Quit);
            }
            function sizeHandler () {
                if (sizeHandler[0] == 'SIZE_CHANGED') {
                    updateScreenSize ();
                }
            }

            function updateScreenSize () { //all the calculations are done here
              screenSize.x = Browser.getWidth();//here screen size is put into a global variable because it is used in other function of the script
              screenSize.y = Browser.getHeight();// but it can also be put into a local variable (var h = ...)

              if (screenSize.x > 128) { //we enter into scalable mode, limit calculation as possible

                var min = screenSize.x;
                if (screenSize.y < min) min = screenSize.y;
                var offset = Math.floor(screenSize.x/10); //example for part 2°) of aspect ratio paragraph
                var offsetY = Math.floor(screenSize.y/10);

                offsetL[0] = offset; offsetL[1] = offset; offsetL[2] = offset;
                offsetL[3] = 0; offsetL[4] = -offset; offsetL[5] = -offset; offsetL[0] = -offset;
                offsetR[0] = offset; offsetR[1] = offset; offsetR[2] = 0; offsetR[3] = -offset;
                offsetR[4] = -offset; offsetR[5] = -offset; offsetL[6] = -offset;
                bannerRec.size.x = screenSize.x;
                bannerRec.size.y = screenSize.y * 0.23;
                bannerTrs.translation.y = offsetY + ((bannerRec.size.y - screenSize.y )/ 2); //height of softKeys + height/2 of carrousel banner
                posX = Math.floor(screenSize.x/5);
                arrowRec.size.x = Math.floor(min*0.05);
                arrowRec.size.y = Math.floor(arrowRec.size.x*1.66); //example for part 1°) of aspect ratio paragraph
                laTrs.translation.x = ((arrowRec.size.x - screenSize.x)/2) + margin;
                raTrs.translation.x = ((screenSize.x - arrowRec.size.x)/2) - margin;
                appTicker.size.x = screenSize.x - (2*(arrowRec.size.x+margin));
                appTicker.size.y = bannerRec.size.y - (2*margin);
                appTicker.translation.y = (offsetY/2);
                counterTrs.translation.y = -appTicker.translation.y;
              } else { //we enter into 128 width mode : put constants and some calculation depending on height
                posX = 25;
                bannerTrs.translation.y = (Browser.getHeight() / -2) + 36; //height of softKeys + height/2 of carrousel banner
              }
            }
            function tick (val, time) { //a function for animation to navigate into the carousel
                if (way == 1) {
                    for (var i = 0; i < 6; i++) {
                        item = items[i];
                        //item.translation.x = (84 - (42*val)) - (i*42);
                        item.translation.x = (posX * ((3 - val) - i));
                        item.translation.x += offsetR[i] ;
                    }
                } else if (way == -1) {
                    for (var i = 0; i < 6; i++) {
                        item = items[i];
                        //item.translation.x = (42 + (42*val)) - (i*42);
                        item.translation.x = (posX * ((2 + val) - i));
                        item.translation.x += offsetL[i] ;
                    }
                }
             }
            ...
        "
     }
     ROUTE SIZE_CHANGED.data_changed TO SCRIPT.sizeHandler