Java Doc for CustomItem.java in  » 6.0-JDK-Modules » j2me » javax » microedition » lcdui » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Like other Items, CustomItems have the concept of minimum and preferred sizes. These pertain to the total area of the Item, which includes space for the content, label, borders, etc. See Item Sizes for a full discussion of the areas and sizes of Items.

CustomItem subclasses also have the concept of the content size, which is the size of only the content area of the CustomItem. The content area is a rectangular area inside the total area occupied by the CustomItem. The content area is the area within which the CustomItem subclass paints and receives input events. It does not include space consumed by labels and borders. The implementation is responsible for laying out, painting, and handling input events within the area of the Item that is outside the content area.

All coordinates passed between the implementation and the CustomItem subclass are relative to the item's content area, with the upper-left corner of this area being located at (0,0). Size information passed between the implementation and the CustomItem subclass with the CustomItem.getMinContentHeight getMinContentHeight , CustomItem.getMinContentWidth getMinContentWidth , CustomItem.getPrefContentHeight getPrefContentHeight , CustomItem.getPrefContentWidth getPrefContentWidth , and CustomItem.sizeChanged sizeChanged methods all refer to the size of the content area. The implementation is responsible for computing and maintaining the difference between the size of the content area and the size of the total area of the Item as reported by the Item size methods Item.getMinimumHeight Item.getMinimumHeight , Item.getMinimumWidth Item.getMinimumWidth , Item.getPreferredHeight Item.getPreferredHeight , and Item.getPreferredWidth Item.getPreferredWidth .

The implementation may disregard sizing information returned from a CustomItem if it exceeds limits imposed by the implementation's user interface policy. In this case, the implementation must always report the actual size granted to the CustomItem via the CustomItem.sizeChanged sizeChanged and the CustomItem.paint paint methods. For example, this situation may occur if the implementation prohibits an Item from becoming wider than the screen. If the CustomItem subclass code returns a value from getMinContentWidth that would result in the CustomItem being wider than the screen, the implementation may assign a width smaller than the minimum width returned by getMinContentWidth.

The implementation is allowed to call the CustomItem's content size methods CustomItem.getMinContentHeight getMinContentHeight , CustomItem.getMinContentWidth getMinContentWidth , CustomItem.getPrefContentHeight getPrefContentHeight , and CustomItem.getPrefContentWidth getPrefContentWidth , in any order with respect to other CustomItem methods. For all of these methods, the CustomItem subclass code must return values that are consistent with the current contents of the CustomItem. If the contents changes, it is not sufficient for the CustomItem subclass code simply to begin returning different values from the content size methods. Instead, the subclass code must call the CustomItem.invalidate invalidate method whenever its contents changes. This indicates to the implementation that it may need to perform its layout computation, which will call the content size methods to get new values based on the CustomItem's new contents.

Interaction Modes

The CustomItem class is intended to allow edit-in-place on many items, but it does not allow every conceivable interaction. Desire for flexibility has been balanced against a requirement that these APIs be simple enough to master easily, along with a need to allow for platform-specific variations in look-and-feel, all without sacrificing interoperability.

The general idea is that there are multiple interaction "modes" and that the Form implementation can convey which ones it supports. The CustomItem can then choose to support one or more interaction modes. There is no requirement for a CustomItem to implement all combinations of all interaction modes. Typically, a CustomItem will implement an approach (such as the separate editing screen technique discussed below) that works on all platforms, in addition to a highly interactive approach that relies on a particular interaction mode. At run time, the CustomItem code can query the system to determine whether this interaction mode is supported. If it is, the CustomItem can use it; otherwise, it will fall back to the approach that works on all platforms.

CustomItem can always use item commands to invoke a separate editing screen, although components with a small number of discrete states could simply respond by changing the state and then causing an notifyStateChanged notification. A technique for using a separate editing screen would be to load the value into another Displayable object (such as a List) and then to call Display.setCurrent(Displayable) on it. When the user issues a command (such as "OK") to indicate that editing of this value is complete, the listener can retrieve the value from that Displayable object and then call Display.setCurrentItem(Item) to return to this item.

Keypad Input

The implementation may optionally support delivery of keypad events to the CustomItem. The implementation indicates the level of support by setting the KEY_PRESS, KEY_RELEASE, and KEY_REPEAT bits in the value returned by getInteractionModes. Events corresponding to these bits are delivered through calls to the keyPressed(), keyReleased(), and keyRepeated() methods, respectively. If an implementation supports KEY_RELEASE events, it must also support KEY_PRESS events. If an implementation supports KEY_REPEAT events, it must also support KEY_PRESS and KEY_RELEASE events. If supported, KEY_RELEASE events will generally occur after a corresponding KEY_PRESS event is received, and KEY_REPEAT events will generally occur between KEY_PRESS and KEY_RELEASE events. However, it is possible for the CustomItem to receive KEY_RELEASE or KEY_REPEAT events without a corresponding KEY_PRESS if a key is down when the CustomItem becomes visible.

Key event methods are passed the keyCode indicating the key on which the event occurred. Implementations must provide means for the user to generate events with key codes Canvas.KEY_NUM0 through Canvas.KEY_NUM9, Canvas.KEY_STAR, and Canvas.KEY_POUND. Implementations may also deliver key events for other keys, include device-specific keys. The set of keys available to a CustomItem may differ depending upon whether commands have been added to it.

The application may map key codes to game actions through use of the getGameAction method. If the implementation supports key events on CustomItems, the implementation must provide a sufficient set of key codes and a mapping to game actions such that all game actions are available to CustomItems.

The set of keys and the key events available to a CustomItem may differ from what is available on a Canvas. In particular, on a system that supports traversal, the system might use directional keys for traversal and elect not to deliver these keys to CustomItems. The mapping between key codes and game actions in a CustomItem may differ from the mapping in a Canvas. See Key Events and Game Actions on class Canvas for further information about key codes and game actions.

Pointer Input

The implementation may optionally support delivery of pointer events (such as taps with a stylus) to the CustomItem. The implementation indicates the level of support by setting the POINTER_PRESS, POINTER_RELEASE, and POINTER_DRAG bits in the value returned by getInteractionModes. Events corresponding to these bits are delivered through calls to the pointerPressed(), pointerReleased(), and pointerDragged() methods, respectively. If an implementation supports POINTER_RELEASE events, it must also support POINTER_PRESS events. If an implementation supports POINTER_DRAG events, it must also support POINTER_PRESS and POINTER_RELEASE events. If supported, POINTER_RELEASE events will generally occur after a corresponding POINTER_PRESS event is received, and POINTER_DRAG events will generally occur between POINTER_PRESS and POINTER_RELEASE events. However, it is possible for the CustomItem to receive POINTER_RELEASE or POINTER_DRAG events without a corresponding POINTER_PRESS if the pointer is down when the CustomItem becomes visible.

The (x,y) location of the pointer event is reported with every pointer event. This location is expressed in the coordinate system of the CustomItem, where (0,0) is the upper-left corner of the CustomItem. Under certain circumstances, pointer events may occur outside the bounds of the item.

Traversal

An implementation may support traversal internal to a CustomItem, that is, the implementation may temporarily delegate the responsibility for traversal to the item itself. Even if there is only one traversal location inside the CustomItem, the item may want support the internal traversal protocol so that it can perform specialized highlighting, animation, etc. when the user has traversed into it.

The implementation indicates its support for traversal internal to a CustomItem by setting one or both of the TRAVERSE_HORIZONTAL or TRAVERSE_VERTICAL bits in the value returned by getInteractionModes(). If neither of these bits is set, the implementation is unwilling to let CustomItems traverse internally, or the implementation does not support traversal at all. If the implementation does support traversal but has declined to permit traversal internal to CustomItems, the implementation will supply its own highlighting outside the CustomItem's content area.

The CustomItem need not support internal traversal at all. It can do this by returning false to the initial call to the traverse method. (This is the default behavior if this method hasn't been overridden by the CustomItem.) If this occurs, the system must arrange for the user to be able to traverse onto and past this item. The system must also arrange for proper scrolling to take place, particularly if the item exceeds the height of the screen, regardless of whether internal traversal is occurring.

An implementation may provide support for delivering keypad or pointer events to CustomItems even if it has declined to support delivering traverse events to CustomItems. If an implementation provides support for delivering keypad or pointer events to CustomItems, it must provide a means to do so for every CustomItem, even for those that have refused internal traversal by returning false to the initial traverse() call. This implies that such implementations must still support some notion of focus for an item, even if that item is not supporting internal traversal.

See the documentation for the CustomItem.traverse traverse method for a full specification of the behavior and responsibilities required for the item to perform internal traversal.

Item Appearance

The visual appearance of each item consists of a label (handled by the implementation) and its contents (handled by the subclass).

Labels are the responsibility of the implementation, not the item. The screen area that is allocated to the CustomItem for its contents is separate from the area that the implementation uses to display the CustomItem's label. The implementation controls the rendering of the label and its layout with respect to the content area.

The CustomItem is responsible for painting its contents whenever the paint method is called.

The colors for foreground, background, highlighted foreground, highlighted background, border, and highlighted border should be retrieved from Display.getColor . This will allow CustomItems to match the color scheme of other items provided with the device. The CustomItem is responsible for keeping track of its own highlighted and unhighlighted state.

The fonts used should be retrieved from Font.getFont . This will allow them to match the fonts used by other items on the device for a consistent visual appearance.

If the size of a CustomItem changes while it is visible on the display, it may trigger an automatic repaint request.

KEY_PRESS has the value 4.

KEY_RELEASE has the value 8.

KEY_REPEAT has the value 0x10.

NONE has the value 0.

POINTER_DRAG has the value 0x80.

POINTER_PRESS has the value 0x20.

POINTER_RELEASE has the value 0x40.

TRAVERSE_HORIZONTAL has the value 1.

TRAVERSE_VERTICAL has the value 2.

The mapping of key codes to game actions may differ between CustomItem and Canvas.

The width parameter is the tentative width assigned to the content area. The subclass code may use this value in its computation of the preferred height. The width parameter will be -1 if the implementation has not assigned a tentative value for the width. Otherwise, width will have a specific value if the application has locked the width of the CustomItem or if the container's layout algorithm has already computed a tentative width at the time of this call. The subclass must not assume that the tentative width passed or the preferred height returned will be granted. The actual size granted is reported in the CustomItem.sizeChanged sizeChanged and CustomItem.paint paint methods.

The height parameter is the tentative height assigned to the content area. The subclass code may use this value in its computation of the preferred width. The height parameter will be -1 if the implementation has not assigned a tentative value for the height. Otherwise, height will have a specific value if the application has locked the height of the CustomItem or if the container's layout algorithm has already computed a tentative height at the time of this call. The subclass must not assume that the tentative height passed or the preferred width returned will be granted. The actual size granted is reported in the CustomItem.sizeChanged sizeChanged and CustomItem.paint paint methods.

The default implementation of this method does nothing.

Other values of the Graphics object are as follows:

• the current color is black;
• the font is the same as the font returned by Font.getDefaultFont Font.getDefaultFont() ;
• the stroke style is Graphics.SOLID SOLID ;

The paint() method will be called only after showNotify() call on this item and before a subsequent hideNotify() call on this item, in other words, only when at least a portion of the item is actually visible on the display. In addition, the paint() method will be called only if the item's width and height are both greater than zero.

The default implementation of this method does nothing.

If the size of a CustomItem changes while it is visible on the display, it may trigger an automatic repaint request. If this occurs, the call to sizeChanged will occur prior to the call to paint. If the CustomItem has become smaller, the implementation may choose not to trigger a repaint request if the remaining contents of the CustomItem have been preserved. Similarly, if the CustomItem has become larger, the implementation may choose to trigger a repaint only for the new region. In both cases, the preserved contents must remain stationary with respect to the origin of the CustomItem. If the size change is significant to the contents of the CustomItem, the application must explicitly issue a repaint request for the changed areas. Note that the application's repaint request should not cause multiple repaints, since it can be coalesced with repaint requests that are already pending.

If the size of the item's content area changes while it is not visible, calls to this method may be deferred. If the size had changed while the item was not visible, sizeChanged will be called at least once before the item becomes visible once again.

The default implementation of this method does nothing.

The implementation indicates support for internal traversal within a CustomItem by setting one or both of the TRAVERSE_HORIZONTAL or TRAVERSE_VERTICAL bits in the value returned by the getInteractionModes method. The dir parameter indicates the direction of traversal by using Canvas game actions Canvas.UP, Canvas.DOWN, Canvas.LEFT, and Canvas.RIGHT, or the value NONE, which indicates that there is no specific direction associated with this traversal event. If the TRAVERSE_HORIZONTAL bit is set, this indicates that the Canvas.LEFT and Canvas.RIGHT values will be used to indicate the traversal direction. If the TRAVERSE_VERTICAL bit is set, this indicates that the Canvas.UP and Canvas.DOWN values will be used to indicate the traversal direction. If both bits are set, all four direction values may be used for the traversal direction, indicating that the item should perform two-dimensional traversal. The dir parameter may have the value NONE under any combination of the TRAVERSE_VERTICAL and TRAVERSE_HORIZONTAL bits.

Although Canvas game actions are used to indicate the traversal direction, this does not imply that the keys mapped to these game actions are being used for traversal, nor that that keys are being used for traversal at all.

The viewportWidth and viewportHeight parameters indicate the size of the viewable area the item's container has granted to its items. This represents the largest area of the item that is likely to be visible at any given time.

The visRect_inout parameter is used both for passing information into this method and for returning information from this method. It must be an int[4] array. The information in this array is a rectangle of the form [x,y,w,h] where (x,y) is the location of the upper-left corner of the rectangle relative to the item's origin, and (w,h) are the width and height of the rectangle. The return values placed into this array are significant only when the traverse() method returns true. The values are ignored if the traverse() method returns false.

When this method is called, the visRect_inout array contains a rectangle representing the region of the item that is currently visible. This region might have zero area if no part of the item is visible, for example, if it is scrolled offscreen. The semantics of the rectangle returned are discussed below.

The CustomItem must maintain state that tracks whether traversal is within this item, and if it is, it must also record the current internal location. Initially, traversal is outside the item. The first call to the traverse() method indicates that traversal has entered the item. Subsequent calls to this method indicate that traversal is occurring within this item. Traversal remains within the item until the traverseOut method is called. The CustomItem must keep track of its traversal state so that it can distinguish traversal entering the item from traversal within the item.

When traversal enters the item, the traversal code should initialize its internal traversal location to the "first" location appropriate for the item's structure and the traversal direction. As an example of the latter policy, if the traversal direction is DOWN, the initial location should be the topmost internal element of the item. Similarly, if the traversal direction is UP, the initial location should be the bottommost element of the item. The CustomItem should still choose the "first" location appropriately even if its primary axis is orthogonal to the axis of traversal. For example, suppose the traversal mode supported is TRAVERSE_VERTICAL but the CustomItem is structured as a horizontal row of elements. If the initial traversal direction is DOWN, the initial location might be the leftmost element, and if the initial traversal direction is UP, the initial location might be the rightmost element.

Traversal may enter the item without any specific direction, in which case the traversal direction will be NONE. This may occur if the user selects the item directly (e.g., with a pointing device), or if the item gains the focus because its containing Form has become current. The CustomItem should choose a default traversal location. If the CustomItem had been traversed to previously, and if it is appropriate for the user interface of the CustomItem, the previous traversal location should be restored.

When traversal occurs within the item, the internal traversal location must be moved to the next appropriate region in the direction of traversal. The item must report its updated internal traversal location in the visRect_inout return parameter as described below and return true. The item will typically provide a highlight to display the internal traversal location to the user. Thus, the item will typically also request repaints of the old and new traversal locations after each traversal event. There is no requirement that the area the item requests to be repainted is the same as the area returned in the visRect_inout rectangle. The system will combine any repaint requests with any additional repainting that may occur as a result of scrolling.

The traverse() method may be called with a direction of NONE when the traversal is already within the CustomItem. This will occur in response to the CustomItem subclass code having called the invalidate() method. In this case, the CustomItem should simply return its current notion of the traversal location. This mechanism is useful if the CustomItem needs to update the traversal location spontaneously (that is, not in response to a traversal event), for example, because of a change in its contents.

If the internal traversal location is such that the traversal event would logically cause traversal to proceed out of the item, the item should return false from the traverse() method. For example, if the current traversal location is the bottommost internal element of the item, and the traversal direction is DOWN, the traverse() method should simply return false. In this case the method need not update the values in the visRect_inout array. The item must leave its internal traversal location unchanged, and it should not request a repaint to update its highlighting. It should defer these actions until the traverseOut() method is called. The system will call the traverseOut() method when traversal actually leaves the item. The system might not call the traverseOut() method, even if traverse() has returned false, if this item is at the edge of the Form or there is no other item beyond to accept the traversal. Even if the traverse() method returns false, the traversal location is still within this item. It remains within this item until traverseOut() is called.

Note the subtle distinction here between the initial traverse() call signifying entry into the item and subsequent calls signifying traversal within the item. A return value of false to the initial call indicates that this item performs no internal traversal at all, whereas a return of false to subsequent calls indicates that traversal is within this item and may now exit.

The width and height of the rectangle returned in the visRect_inout array are used by the Form for scrolling and painting purposes. The Form must always position the item so that the upper left corner of this rectangle, as specified by the (x,y) position, is visible. In addition, the item may also specify a width and height, in which case the Form will attempt to position the item so that as much of this rectangle as possible is visible. If the width and height are larger than the size of the viewport, the bottom and right portions of this rectangle will most likely not be visible to the user. The rectangle thus returned will typically denote the size and location of one of the item's internal elements, and it will also typically (though not necessarily) correspond to where the element's highlight will be painted. Width and height values of zero are legal and are not treated specially. Negative values of width and height are treated as if they were zero.

There is no requirement on the location of the rectangle returned in the visRect_inout array with respect to the traversal direction. For example, if the CustomItem implements internal scrolling, a traversal direction of DOWN may cause the item's contents to scroll upwards far enough so that the rectangle returned may be above its old location. CustomItem subclasses must ensure that continued traversal in one direction will eventually reach the edge of the item and then traverse out by returning false from this method. CustomItems must not implement "wraparound" behavior (for example, traversing downwards from the bottommost element moves the traversal location to the topmost element) because this will trap the traversal within the item.

If the CustomItem consists of internal elements that are smaller than the container's viewport, the rectangle returned should be the same size as one of these elements. However, the CustomItem might have contents whose elements are larger than the viewport, or it might have contents having no internal structure. In either of these cases, the item should return a rectangle that best represents its idea of the content area that is important for the user to see. When traversal occurs, the item should move its traversal location by an amount based on the viewport size. For example, if the viewport is 80 pixels high, and traversal occurs downwards, the item might move its traversal location down by 70 pixels in order to display the next screenful of content, with 10 pixels overlap for context.

All internal traversal locations must be reachable regardless of which traversal modes are provided by the implementation. This implies that, if the implementation provides one-dimensional traversal, the CustomItem must linearize its internal locations. For example, suppose the traversal mode is TRAVERSE_VERTICAL and the CustomItem consists of a horizontal row of elements. If the traversal direction is DOWN the internal traversal location should move to the right, and if the traversal direction is UP the internal traversal location should move to the left. (The foregoing convention is appropriate for languages that use left-to-right text. The opposite convention should be used for languages that use right-to-left text.) Consider a similar example where the traversal mode is TRAVERSE_VERTICAL and the CustomItem consists of a grid of elements. A traversal direction of DOWN might proceed leftwards across each row, moving to the next row downwards when the location reaches the rightmost element in a row.

If the implementation provides two-dimensional traversal but the CustomItem is one-dimensional, a traversal direction along the item's axis should traverse within the item, and a traversal direction orthogonal to the item's axis should cause immediate traversal out of the item by returning false from this method. For example, suppose a CustomItem is implementing a vertical stack of elements and traversal is already inside the item. If a traverse event is received with direction UP or DOWN, the traverse() method should move to the next element and return true. On the other hand, if a traverse event is received with direction RIGHT or LEFT, the traverse() method should always return false so that traversal exits the item immediately. An item that implements internal traversal should always accept entry - that is, the initial call to traverse() should return true - regardless of the axis of the traversal direction.

If the traverse() method returns false when traversal is entering the item, this indicates to the system that the item does not support internal traversal. In this case, the item should not perform any of its own highlighting, and the system will perform highlighting appropriate for the platform, external to the item.

The default implementation of the traverse() method always returns false.