Just An Application

June 23, 2009

What’s New In MIDP 3.0 ? Part 18: LCDUI – Displays

Filed under: Java, JME, LCDUI, MIDlets, MIDP, MIDP3, MIDP3API, MIDP3LCDUI — Tags: , , , , , , , — Simon Lewis @ 9:28 am

1. The Display Model

  • A device has one or more physical displays.

  • Each physical display may support sharable and non-sharable functionality.

  • The supported functionality may differ between physical displays.

  • A Display gives a MIDlet access to a fixed set of the functionality of a corresponding physical display.

  • A MIDlet will always have access to a primary display corresponding to the main physical display of the device.

  • If a device has additional physical displays a MIDlet will have access to corresponding secondary Displays.

  • If a physical display has two or more operating modes each with a discrete set of functionality a MIDlet will have access to those
    modes via two or more Displays.

2. Display Characteristics

2.1 Getting The Display’s Height

A Display’s height in pixels can be obtained by calling its

    public int getHeight()

method.

The value returned is the maximum height available for the display of a Displayable including its Title, Ticker, Commands and Menus, if present.

2.2 Getting The Display’s Width

A Display’s width in pixels can be obtained by calling its

    public int getWidth()

method.

The value returned is the maximum width available for the display of a Displayable including its Title, Ticker, Commands and Menus, if present.

2.3 Getting The Display’s Dot Pitch

A Display’s dot pitch can be obtained by calling its

    public int getDotPitch()

method.

The value returned is the distance between adjacent pixels in micrometers (1 x 10-6m).

2.4 Does The Display Support Pointer Events ?

Whether or not a Display supports Pointer events can be determined by calling its

    public boolean hasPointerEvents()

method.

The method returns true if the Display is capable of reporting Pointer pressed and released events.

Notes

  1. This method effectively supercedes the Canvas.hasPointerEvents() method. Whether Pointer events are supported by a Canvas is actually dependent upon the Display on which the Canvas is currently visible.
  2. It is not clear why, other than for convenience, this functionality is not implemented using the capabilites mechanism.

2.5 Does The Display Support Pointer Motion Events ?

Whether or not a Display supports Pointer Motion events can be determined by calling its

    public boolean hasPointerMotionEvents()

method.

The method returns true if the Display is capable of reporting Pointer motion eventst.

Note

  1. This method effectively supercedes the Canvas.hasPointerMotionEvents() method. Whether Pointer motion events are supported by a Canvas is actually dependent upon the Display on which the Canvas is
    currently visible.
  2. It is not clear why, other than for convenience, this functionality is not implemented using the capabilites mechanism.

2.6 Is The Display Built-in ?

Whether or not the corresponding physical of a Display is built-in can be determined by calling its

    public boolean isBuiltIn()

method.

The method returns true if the corresponding physical display is built-in, that is, if it is an integral part of the device. If it is then the corresponding Display will never become unusable as the result of the removal of the corresponding physical display.

3. Display Capabilities

The functionality supported by a given Display is specified at runtime using capabilities, where a capability typically represents a discrete LCDUI feature.

The following capabilities are defined as constants in the Display class.

  • SUPPORTS_ALERTS
  • SUPPORTS_COMMANDS
  • SUPPORTS_FILESELECTORS
  • SUPPORTS_FORMS
  • SUPPORTS_IDLEITEM
  • SUPPORTS_INPUT_EVENTS
  • SUPPORTS_LISTS
  • SUPPORTS_MENUS
  • SUPPORTS_ORIENTATION_LANDSCAPE
  • SUPPORTS_ORIENTATION_LANDSCAPE180
  • SUPPORTS_ORIENTATION_PORTRAIT
  • SUPPORTS_ORIENTATION_PORTRAIT180
  • SUPPORTS_TABBEDPANES
  • SUPPORTS_TEXTBOXES
  • SUPPORTS_TICKER
  • SUPPORTS_TITLE

The constants are bit-flags and can be combined using bit-wise OR.

A MIDlet’s primary Display will support all LCDUI features but a secondary Display may not.

All Displays provides basic Canvas support.

The capabilities of a Display are fixed.

3.1 Getting A Display’s Capabilities

A Display’s capabilities can be obtained using its

 public int getCapabilities()

method.

The return value will either be the bit-wise OR’ed combination of the supported capabilities, or 0 indicating that the Display only provides basic Canvas support.

3.2 DisplayCapabilityException

A DisplayCapabilityException is thrown when an attempt is made to perform an operation which directly or indirectly involves a Display which does not support the functionality required for the operation. For example, passing an instance of Form to the setCurrent() method of a Display which does not support Forms.

4. Display State

A Display can be in one of three states

  • Foreground,
  • Background, or
  • Visible

depending upon its current level of access to the functionality of the corresponding physical display.

4.1 Foreground

If a Display is in the Foreground state then it currently has exclusive access to all non-sharable functionality of the corresponding physical display, and first-call on any sharable functionality.

4.2 Background

If a Display is in the Background state then it currently has no access to the functionality of the corresponding physical display.

4.3 Visible

If a Display is in the Visible state then it has access to at least one pixel of the corresponding physical display, but it has no access to any of the non-sharable functionality.

4.4 Runtime Constants

The possible display states are represented by the following constants defined in the Display class

  • STATE_BACKGROUND
  • STATE_FOREGROUND
  • STATE_VISIBLE

4.5 Getting The Current Display State

The current state of the Display can be obtained using the Display’s

    public int getDisplayState()

method which will return one of the constants listed above.

5. Hardware State

The hardware state of a Display is equivalent to the state of the corresponding physical display.
The physical display may be

  • Enabled,
  • Disabled, or
  • Absent

The hardware state of a MIDlet’s primary display will never be Absent.

5.1 Enabled

If the hardware state of a Display is Enabled then the functionality of the corresponding physical display is available to the Display.

5.2 Disabled

If the hardware state of a Display is Disabled then the functionality of the corresponding physical display is not available to the Display.

5.3 Absent

If the hardware state of a Display is Absent then the corresponding physical display is no longer available and the Display itself is no longer usable.

5.4 Runtime Constants

The possible hardware states are represented by the following constants defined in the Display class

  • DISPLAY_HARDWARE_ABSENT
  • DISPLAY_HARDWARE_DISABLED
  • DISPLAY_HARDWARE_ENABLED

5.5 Getting The Current Hardware State

The current hardware state of a given Display can be obtained used the Display’s

    public int getHardwareState()

method which will return one of the constants listed above.

6. Activity Mode

The activity mode of a Display may be either Normal or Active.

If a Display is in the Foreground state and its activity mode is Normal then the corresponding physical display may enter a reduced functionality power-saving state if the current power management policies of the device allow it.

If a Display is in the Foreground state and its activity mode is Active then the corresponding physical display should remain in a fully functional state.

If a Display in the Foreground state changes its activity mode from Normal to Active and the corresponding physical display is in a power-saving state it should return to a fully functional state.

The possible activity modes are represented by the following constants defined in the Display class.

  • MODE_ACTIVE
  • MODE_NORMAL

6.1 Getting The Current Activity Mode

The current activity mode of a Display can be obtained by calling it’s

    public int getActivityMode()

method which will return one of the runtime constants listed above.

6.2 Setting The Current Activity Mode

The current activity mode of a Display can be set by calling it’s

    public void setActivityMode(int mode)

method.

The mode argument must be one of the constants listed above.

7. Display Orientation

A Display may support more than one orientation.

Possible orientations are

Landscape Display’s width is greater than its height
Landscape 180 Landscape with content rotated through 180 degrees
Portrait Display’s height is greater than its width
Portrait 180 Portrait with content rotated through 180 degrees

The orientations supported by a Display can be determined by calling its getCapabilities() method.

7.1 Runtime Constants

The possible orientatations are represented by the following constants defined in the Display class

  • ORIENTATION_LANDSCAPE
  • ORIENTATION_LANDSCAPE180
  • ORIENTATION_PORTRAIT
  • ORIENTATION_PORTRAIT180

7.2 Getting The Orientation

The current orientation of the Display can be obtained by calling its

    public int getOrientation()

method which will return one of the constants listed above.

7.3 Setting The Preferred Orientation

The preferred orientation of a Display can be set using its

    public void setPreferredOrientation(int orientation)

method where orientation must be one of the constants listed above.

Note

It is not clear from the specification exactly what setPreferredOrientation() does. It states

This call may not have an effect on the actual orientation of the display if the specified orientation is not supported on the device.

It then goes on to say

The application may use getOrientation() to detect the actual orientation of the display after this call.

which would seem to imply that it is not guaranteed to do anything even if the specified orientation is supported by the Display.

More generally it is not clear what it means for a Display to support a given orientation. One possible interpretation is that if a Display supports more than one orientation, then, if the orientation of the Display changes it will automatically re-render all visible UI elements appropriately. This would seem to make sense as there is no API by which a MIDlet could achieve the same effect. Other aspects of the UI such as the size of the UI elements are potentially under the control of the MIDlet and are presumably, therefore, its responsibility.

8. Display Events

A MIDlet can listen for the addition of secondary Displays, and for changes in the

  • display state
  • hardware state
  • orientation
  • size

of individual Displays using an instance of the DisplayListener interface.

All Display events are serialized with respect to other LCDUI events.

Note

An orientation change may also result in a size change, but the specification does not explicitly state that the resulting events must occur in a particular order.

8.1 Adding A DisplayListener

A MIDlet can begin listening by using the Display method

    public static void addDisplayListener(DisplayListener l)

to add a DisplayListener.

8.2 Removing A DisplayListener

A MIDlet can stop listening using the Display method

    public static void removeDisplayListener(DisplayListener l)

to remove a DisplayListener added previously.

8.3 DisplayListener

Events are reported to a DisplayListener using event specific methods as follows.

8.3.1 Addition

The addition of secondary display is reported via the

    public void displayAdded(Display d)

method.

8.3.2 State Changes

Changes to the state of a Display are reported via the

    public void displayStateChanged(Display d, int newState)

method.

The newState argument will be one of the Display state runtime constants.

8.3.3 Hardware State Changes

Changes to the hardware state of a Display are reported via the

    public void hardwareStateChanged(Display d, int newState)

method.

The newState argument will be one of the Hardware state runtime constants.

8.3.4 Orientation Changes

Changes to the orientation of a Display are reported via the

     public void void orientationChanged(Display d, int newOrientation)

method.

The newOrientation argument will be one of the Orientation runtime constants.

8.3.5 Size Changes

Changes to the size of a Display are reported via the

    void sizeChanged(Display d, int w, int h)

method.

The arguments w and h are the new width and height of the Display respectively.

9. Getting Displays

9.1 Getting The Primary Display

The existing Display method

    public static Display getDisplay(MIDlet m)

will return the primary Display for the given MIDlet.

9.2 Getting Displays With Specific Capabilities

The new Display method

    public static Display[] getDisplays(int capabilities)

can be used to obtain a list of all the Displays currently available, or a list of those which support a specified set of capabilities.

If capabilities is 0 then a list available Displays will be returned, with the primary Display first.

If capabilities is a bit-wise ORed combination of the runtime constants representing capabilities, then the list of Displays supporting those capabilities will be returned, with the primary Display first.

Note

The method documentation states

Since the Primary Display must support all capabilities, it is always returned as the first element regardless of the capabilities requested.

For this to be true the Primary display must not only support all the LCDUI features, but all the possible orientations as well. It is not clear what supporting all possible orientations entails nor whether it is necessarily feasible on every device.

10. Transient Secondary Displays

The physical display corresponding to a secondary Display can become unavailable. In this case the hardware state of the secondary Display will change to Absent. Once this happens the secondary Display is no longer usable, and calls to methods such as setCurrent(Displayable) will throw an IllegalStateException.

If the physical display corresponding to the secondary Display becomes available again it
will be reported as a new Display via a call to the DisplayaListener.displayAddedd(Display) method.

12. Backwards Compatibility

Some existing methods now throw new exceptions. For example, Display.setCurrent(Displayable) can now throw a DisplayCapabiltyException or an IllegalStateException. However, as required to ensure binary compatibility, all new exceptions thrown are RuntimeExceptions. In addition these exceptions cannot occur when using the Primary display which is the only Display that a legacy MIDlet has access to,


Copyright (c) 2009 By Simon Lewis. All Rights Reserved.

Advertisements

Leave a Comment »

No comments yet.

RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Blog at WordPress.com.

%d bloggers like this: