Removing the NotificationListener via the Notification.setListener(NotificationListener) method no longer removes the Notification as well.
This eliminates the inconsistency between its behaviour and the documentation describing the Notification life-cycle which I noted in the original post.
The other minor issues noted in my original post still exist.
Copyright (c) 2009 By Simon Lewis. All Rights Reserved.
Links fixed to point at the right versions of the static getFont method, i.e.,
Font.getFont(int)
Scope of the Font created is now limited to the MIDlet that created it.
Implementations MUST insure that the availability and use of fonts created using createFont method is limited to the execution environment of a [sic] MIDlet that instantiated the font.
Changed from MIDlet Suite.
Documentation for all three methods has been updated to explicitly specify that the constant STYLE_UNDERLINED is supported in their respective style arguments.
The specification of the static method Font.getStyle(String) however, has not been updated to match. Possibly it does not need to be. Who knows ?
Font now has a hashCode, which of course it should since it over-rides the equals method.
Unfortunately how the hash code should be computed is apparently a secret, since all the specification says is
the hashcode is computed from the font face name, style, pixelSize, ascent and descent
None apart from the secret hash code algorithm and that only affects implementors.
Copyright (c) 2009 By Simon Lewis. All Rights Reserved.
The following has been added to the end of the Exact Placement of Commands section
of the Display class documentation.
On each callback of
CommandLayoutPolicy.onCommandLayout(Displayable), implementation MUST first disassociateCommandandMenu
with their respective previous placements. At the beginning of each callback ofCommandLayoutPolicy.onCommandLayout(Displayable)method,
Displayable.getCommand(int)orDisplayable.getMenu(int)will returnnullfor every placement.
As I said in my original post
- The specification does not contain an explicit definition of the state of a Display’s placements when the onLayout(Displayable)[sic] method is called, that is, whether Commands and/or Menus previously placed on the current Display by the Displayable are still present or whether all Commands and/or Menus must be explicitly placed each time the method is called. This makes implementing the method perhaps more interesting than it ought to be.
Well now it does. Every time you layout a Displayable’s Commands you start with a clean slate.
The setCommand(Command,int) method no longer throws an IllegalArgumentException when the placement
is associated with a placement that does not support commands
possibly because it is actually not possible for a placement not to support Commands.
It is hard to be sure because the Item.setCommand(Command,int) method will apparently still throw an IllegalArgumentException when the placement
is associated with a placement that does not support commands
The CommandLayoutPolicy now looks like this. Actually it doesn’t because I have re-formatted it. In Chrome, Firefox and Safari the formatting is all over the place, as it is in the PDF version.
class MyCanvas extends Canvas implements CommandLayoutPolicy {
MyCanvas() {
setCommandLayoutPolicy(this);
}
void sort(Command[] commands, int[] positions) {
// sort the commands in the correct order depending on the positions available.
// Implementation can use Display's getCommandPreferredPlacements to get the recommended
// placement for each Command.
}
public void onCommandLayout(Displayable displayable) {
Display display = displayable.getCurrentDisplay();
final int border = Display.SOFTKEY_BOTTOM;
int[] positions = display.getExactPlacementPositions(border);
int numOfPositions = positions.length;
Command[] cmd = displayable.getCommands();
sort(cmd, positions);
if (cmd.length <= numOfPositions) {
for (int i = 0; i < cmd.length; ++i) {
displayable.setCommand(cmd[i], positions[i]);
}
} else {
for (int i = 0; i < numOfPositions ; ++i) {
displayable.setCommand(cmd[i], positions[i]);
}
int[] menuSupportedPlmts = display.getMenuSupportedPlacements();
if( menuSupportedPlmts != null ) {
Menu options = new Menu("More", null, null);
// first add the remaining commands in the Menu
for (int i = numOfPositions; i < cmd.length; ++i) {
options.append(cmd[i]);
}
// Get the first preferred placement of Menu
int menuPlmt = menuSupportedPlmts[0];
// check if this placement already occupied by Command
if( displayable.getCommand(menuPlmt) != null ) {
//add the existing Command in Menu, otherwise the existing
// Command will be removed from the Displayable according to
//setMenu() method
//
options.append(displayable.getCommand(menuPlmt));
}
displayable.setMenu(options, menuPlmt);
}
}
}
}
This is an improvement on the previous version which was flat-out broken. Note that it still doesn’t check the return value of the call to Display.getExactPlacementPositions(int).
The changes above are the only ones that I have found. Of the original issues I raised they address two if you are being charitable.
What is the state of the Displayable with respect to Command layout when the CommandLayoutPolicy.onCommandLayout(Displayable) method is invoked ? It is a clean slate
Can there be placements which do not support Commands ? Probably not.
Everything else is still up for grabs. Developers, assuming there are going to be any, are going to have to try it and see what happens, and then hope it happens the same way everywhere, which is the past has not been a guaranteed recipe for success.
Possibly if somebody had attempted to write a real-world example for the specification the Command layout feature itself would have been better specified. The example provided effectively does no more than provide the existing default behaviour.
Copyright (c) 2009 By Simon Lewis. All Rights Reserved.
The semantics of the depth returned by the method Menu.getMenuDepth() have been changed.
The method now
Returns this menu’s depth within its menu tree. The top menu is of depth 0, the menus attached to it are of depth 1, 2, etc. The top menu is the menu in the menu tree that has no parent menu . If a menu is attached to both a Displayable and another menu, its depth is calculated based on the menu to which it is attached. For instance, a menu A is a sub-menu of menu B and is also attached to a Displayable. If menu B is of depth 3, then menu A will return a depth of 4.
Previously, as I observed in my original post, the specification was both contradictory, and seemed to imply, amongst other things, that a Menu could effectively have two depths.
Although it is not a particularly serious issue, despite the changes, it is not exactly clear what having the ability to obtain the depth of a given Menu is actually for.
The depth of a Menu is only significant in the context of the maximum limit on Menu depth.
If you know that a Menu is at the maximum permitted depth then it is true that you know that you definitely cannot add a sub-Menu to it.
If you know that a Menu is not at the maximum permitted depth however, you do not know that you can add a given Menu as a sub-Menu with out knowing whether the Menu you wish to attach itself has any sub-Menus, and if so what the maximum depth of the sub-Menu tree, and you are going to have to compute that.
As I say it is not serious but some use-cases might have helped.
This is also true of the eternally enigmatic Menu.onParentEnabled(true). What is it for ?
Copyright (c) 2009 By Simon Lewis. All Rights Reserved.
The KeyListener interface enables an object to listen for key events associated with a Canvas, CustomItem, or IdleItem
When a key is pressed, released or repeated the listening object is notified with the key code and modifiers.
The KeyListener of a Canvas or Custom Item can be set using their respective
public void setKeyListener(KeyListener listener)
methods.
In each case passing null as the listener argument will result in the current KeyListener, if any, being removed.
For both a Canvas and a CustemItem having a KeyListener does not affect the
protected void keyPressed(int keyCode)
protected void keyReleased(int keyCode)
protected void keyRepeated(int keyCode)
and they will continue to be called.
Copyright (c) 2009 By Simon Lewis. All Rights Reserved
A TextEditor is a UI element which can be used in conjunction with a Canvas, CustomItem, or IdleItem to display and obtain text input from the user.
A TextEditor is the Canvas/CustomItem equivalent of a TextField and supports the same input constraints and modes as a TextField.
A TextEditor can only be associated with a single Canvas or CustomItem, but a Canvas or CustomItem may have multiple TextEditors associated with it.
The implementation is only responsible for the visual representation of the cursor and text. All other visual aspects of a TextEditor, for example, scroll bars if required, are the responsibility of the MIDlet.
The TextEditorChangeListener enables an object to listen for the TextEditor events.
The listening object is notified when
the caret moves
the text changes
the current input language changes
the current input method changes
the direction of the writing language changes
the user traverses away from the TextEditor
Copyright (c) 2009 By Simon Lewis. All Rights Reserved
A Text object is a mutable text container with the ability to layout it’s contents.
In addition to the text it contains, it has the following attributes, all of which can be set by a MIDlet as required.
the width and height of the rectangle within which to layout it’s contents
the initial text layout direction
the text alignment
the paragraph start indentation level
the space in pixels above each line of text
the space in pixels below each line of text
the background colour
the default foreground colour
the default Font
the position and length of the currently highlighted text, if any
the current position, if any, of the caret</p
The colour and Font used to render text can also be set on a section by section basis if required.
The contents of a Text object can be rendered to a Graphics object which means that it can be used in conjunction with a Canvas, CustomItem, IdleItem or mutable Image.
Copyright (c) 2009 By Simon Lewis. All Rights Reserved
The AnimatedImage class is a sub-class of the Image class.
An AnimatedImage is a composite Image which comprises a sequence of Images. It is displayed by displaying the individual Images within the sequence one after another, each Image being replaced by its successor after a specified period of time.
An AnimatedImage may be used anywhere an Image can be used, but an implementation may not necessarily render the AnimatedImage exactly as specified. It may render it statically using the first Image in the sequence, or animate it only for a period of time.
A frame is an individual Image within the sequence of Image’s that comprise the AnimatedImage.
The frame count is the number of Image’s in the sequence of Image’s that comprise the AnimatedImage.
The frame delay is the amount of time, in milliseconds, for which a given frame will be displayed
The index of a given frame is it’s position within the sequence of Image’s that comprise the AnimatedImage.
Frames are indexed from zero so a valid frame index must be greater than or equal to zero and less than the frame count.
The loop count is the number of times the AnimatedImage’s frame sequence will be repeated after it has been shown for the first time.
An AnimatedImage can be created from data in the GIF89a format using any of the following Image method’s
public static Image createImage(java.io.InputStream stream)
throws
java.io.IOException
public static Image createImage(String name)
throws
java.io.IOException
public static Image createImage(byte[] imageData, int imageOffset, int imageLength)
In each case the resulting Image can then be cast to an AnimatedImage.
Whether the resulting Image is in fact an AnimatedImage can be determined by calling the Image’s isAnimated() method.
The frame count of an AnimatedImage can be obtained by calling it’s
public int getFrameCount()
method.
The loop count of an AnimatedImage can be obtained by calling it’s
public int getLoopCount()
method.
The method will return -1 if the frame sequence will be repeated indefitely.
A specific frame of an AnimatedImage can be obtained by calling it’s
public Image getFrame(int index)
method
It is an error if the index argument does not specify a valid frame index and an IndexOutOfBoundsException will e thrown.
The method will return an immutable Image representing the specified frame.
The delay for a specific Frame of an AnimatedImage by calling it’s
public int getFrameDelay(int index)
method.
It is an error if the index argument does not specify a valid frame index and an IndexOutOfBoundsException will e thrown.
Copyright (c) 2009 By Simon Lewis. All Rights Reserved.
A mutable Image with an alpha channel by calling the Image method
public static Image createImage(
int width,
int height,
boolean withAlpha,
int fillColor)
It is an error if either the x or y arguments is less than one and an IllegalArgumentException will be thrown.
The fillColor argument specifies the initial value of each pixel of the created Image.
If the withAlpha argument is true then the fillColor argument is interpreted as a value of the form 0xAARRGGBB, otherwise as a value of the form 0x00RRGGBB
An Image can be created by scaling and transforming all or part of an existing Image by calling the Image method
public static Image createImage(
Image image,
int x,
int y,
int width,
int height,
int transform,
int img_width,
int img_height)
The x, y, width, and height specify the region of the existing Image to use.
It is an error if the specified region is not entirely within the bounds of the source Image, or if the region’s width or height is less than one and an IllegalArgumentException will be thrown.
The transform argument specifies the transform to apply as defined in the Sprite class. It is an error if the specified transform is invalid and an IllegalArgumentException will be thrown.
The img_width and img_height arguments specify the size of the new Image. It is an error if the specified width or height is less than one and an IllegalArgumentException will be thrown.
A MIDlet can get Image data in 16-bit RGB format by calling the Image’s
public void getRGB16(
short[] rgbData,
int offset,
int scanlength,
int x,
int y,
int width,
int height)
method, and in 16-bit ARGB format by calling the Image’s
public void getARGB16(
short[] rgbData,
int offset,
int scanlength,
int x,
int y,
int width,
int height)
method.
A MIDlet can determine whether an Image has an alpha channel by calling it’s
public boolean hasAlpha()
method.
A MIDlet can determine whether an Image is an instance of the sub-class AnimatedImage by calling the Image’s
public boolean isAnimated()
method.
A MIDlet can determine whether an Image is an instance of the sub-class ScalableImage by calling the Image’s
public boolean isScalable()
method.
Copyright (c) 2009 By Simon Lewis. All Rights Reserved.
An IdleItem is a UI element which supports MIDlet access to the ‘idle screen’ associated with a Display on a device.
A Display may not support the use of IdleItems. This can be determined by calling the Display.getCapabilities() method.
The UI functionality available via IdleItem is equivalent to that of a CustomItem since the IdleItem is a sub-class of the CustomItem class.
The IdleItem class is abstract and must be sub-classed to be used.
The foreground, background and highlighted foreground and background colours on an idle screen associated with a given Display can be obtained by calling that Display’s
public int getColor(int colorSpecifier)
method, passing one of the following Display constants
COLOR_IDLE_FOREGROUND
COLOR_IDLE_BACKGROUND
COLOR_IDLE_HIGHLIGHTED_FOREGROUND
COLOR_IDLE_HIGHLIGHTED_BACKGROUND
The Fonts for text and highlighted text on an idle screen can be obtained by calling the Font method
public static Font getFont(int fontSpecifier)
passing the constant
Font.FONT_IDLE_TEXT
or
Font.FONT_IDLE_HIGHLIGHTED_TEXT
respectively.
A MIDlet can get the IdleItem, if any, currently associated with a given Display by calling that
Display’s
public IdleItem getIdleItem()
method.
A MIDlet can request that an IdleItem should appear on the idle screen associated with a given
Display by calling that Display’s
public void setIdleItem(IdleItem idleItem)
method.
If there is an existing associated IdleItem it is removed.
The idleItem argument may be null.
It is an error if the Display does not support IdleItems and a DisplayCapabilityException will be thrown.
It is an error if the specified IdleItem is currently associated with another Display and an IllegalStateException.
The method documentation actually says that an IllegalStateException will be thrown if
If the item is already owned by a Form or Display.
which seems to indicate that it should be possible to add an IdleItem to a Form and that an IdleItem cannot both be a member of a Form and associated with a Display. Presumably the converse also applies.
If after being passed to the Display.setIdleItem(IdleItem) method of a Display
it is added to the idle screen assciated with that Display, then the IdleItem’s
protected void addedToDisplay(Display display)
method will be called.
If having been added it is subsequently removed from idle screen associated with the
Display then the IdleItem’s
protected void removedFromDisplay(Display display)
method will be called.
Copyright (c) 2009 By Simon Lewis. All Rights Reserved.
