Graphics scaling for Canvas

To ease porting from earlier smaller resolution devices, S60 3rd Edition implements Canvas graphics scaling functionality. The functionality is turned on with JAD attributes. The scaling works only in full screen mode of Canvas.

Nokia-MIDlet-Original-Display-Size and Nokia-MIDlet-Target-Display-Size attributes can be used for graphics scaling for full screen LCDUI Canvases. Scaling is done by the platform and it’s not visible to MIDlet.

For legacy MIDlets, it is typically sufficient to define only Nokia-MIDlet-Original-Display-Size attribute, which will then enable the application to use full screen automatically.

The attribute Nokia-MIDlet-Target-Display-Size should only be used in special cases, for example when application resolution needs to be limited to a certain size or aspect ratio. If the attribute is not set, the MIDlet is scaled without changing aspect ratio.

From S60 3rd Edition onwards, a new Nokia-MIDlet-Canvas-Scaling-Orientation-Switch attribute to supplement the existing functionality is introduced. This allows the MIDlet to define whether it supports orientation switching on the defined Original Display Size resolution. Without setting this attribute to true, the scaling is always done to the same orientation regardless of actual device orientation.

This scaling mode is only available in full-screen Canvases. After scaling, the MIDlet is notified via the Canvas.sizeChanged() method.

The scaling options are illustrated in the two figures below:

Figure: Scaling with Nokia-MIDlet-Target-Display-Size attribute

Figure: LCDUI Canvas scaling on orientation switch

For more information on scaling, see document Introduction To The S60 Scalable UI on Nokia Developer.

Side effects of Canvas Graphics scaling

The main side effects concern text drawing.

• The appearance of the text that is drawn to full screen mode Canvases using Graphics methods drawString(), drawSubString(), drawChars() or drawChar() may be worsened in target resolution if the scaling factor is big (for example if the scaling is done from a small resolution to a very big resolution).

• Although scaling is used only in full screen mode Canvases, it affects the font heights also when Graphics methods drawString(), drawSubString(), drawChars() or drawChar() are used for drawing the text to:

  • Normal mode Canvas

  • CustomItem

  • Image (Graphics object is obtained by calling Image.getGraphics())

When scaling is enabled by the attributes, the font height in the cases mentioned above is other than in normal (=scaling not in use) case. This happens because implementation javax.microedition.lcdui.Font cannot know whether Font is being used in full screen mode Canvas or in any of the cases listed above.

Returning the proper font height for scaled full screen Canvases is considered to be more important than for the other cases. Thus, when scaling is enabled, Font.getHeight() always returns the proper height for scaled full screen Canvases. This causes the change of the font height in other (non-scaled) cases that use Graphics object for drawing the text.

Also, when scaling is enabled, the font heights returned for StringItem and List fonts are incorrect. The values returned by StringItem.getFont().getHeight() and List.getFont().getHeight() do not match the actual font height on the screen. This should be a minor issue as the font height in high level LCDUI components is not so important for the application.