SHOW Colour

net.rim.device.api.ui
Class Manager

java.lang.Object
  |
  +--net.rim.device.api.ui.Field
        |
        +--net.rim.device.api.ui.Manager

All Implemented Interfaces:

IComponent, InputMethodListener

Direct Known Subclasses:

DialogFieldManager, FlowFieldManager, HorizontalFieldManager, Screen, VerticalFieldManager

public abstract class Manager

extends Field

Provides fundamental functionality for all field managers.

The system uses manager objects to contain fields. The various manager subclasses handle specific kinds of field layout. This Manager class itself deals with scrolling internally.

Implementing your own layout manager
If you have particular needs, you can implement your own manager. Extend the Manager class, and implement sublayout, getPreferredWidth, and getPreferredHeight. For efficiency, you can override subpaint.

Invoking sublayout prompts your manager to lay out the controlled fields appropriately. In turn, invoke each field's setPosition and layout methods to let the controlled field determine the size it requires.

subpaint should iterate through all the controlled fields, instructing them to paint themselves. You can optimize subpaint by using details of the layout to determine which fields are in the current visible region. To paint a controlled field, invoke paintchild.

styles
Manager does not accept Field.FOCUSABLE_MASK, Field.EDITABLE_MASK.

Field Summary

	static int	BOTTOMMOST Indicates scrolling all the way to the bottom of the manager.
	static int	DOWNWARD Indicates downward scroll direction.
	static long	HORIZONTAL_SCROLL Manager style to turn on horizontal scrolling.
	protected static long	HORIZONTAL_SCROLL_MASK Bitfield mask of the horizontal scroll style specifiers.
	static long	HORIZONTAL_SCROLLBAR Manager style to turn on horizontal scrollbars.
	protected static long	HORIZONTAL_SCROLLBAR_MASK Bitfield mask of the horizontal scrollbar style specifiers.
	static long	LEAVE_BLANK_SPACE Manager style that leave blank space intact.
	static int	LEFTMOST Indicates scrolling all the way to the left of the manager.
	static int	LEFTWARD Indicates scroll direction is to the left.
	static long	NO_HORIZONTAL_SCROLL Manager will not support horizontal scrolling.
	static long	NO_HORIZONTAL_SCROLLBAR Manager will not show horizontal scrollbars.
	static long	NO_SCROLL_RESET Manager style to turn off resetting of scroll value when we leave the manager.
	static long	NO_VERTICAL_SCROLL Manager will not support vertical scrolling.
	static long	NO_VERTICAL_SCROLLBAR Manager will not show vertical scrollbars.
	static int	QUANTA_FONT Indicates that the size of a quanta should be adjusted to the size of the current font on layout.
	static int	RIGHTMOST Indicates scrolling all the way to the right of the manager.
	static int	RIGHTWARD Indicates scroll direction is to the right.
	static int	TOPMOST Indicates scrolling all the way to the top of the manager.
	static int	UPWARD Indicates upward scroll direction.
	static long	VERTICAL_SCROLL Manager style to turn on vertical scrolling.
	protected static long	VERTICAL_SCROLL_MASK Bitfield mask of the vertical scroll style specifiers.
	static long	VERTICAL_SCROLLBAR Manager style to turn on vertical scrollbars.
	protected static long	VERTICAL_SCROLLBAR_MASK Bitfield mask of the vertical scrollbar style specifiers.

Fields inherited from class net.rim.device.api.ui.Field

EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, READONLY, USE_ALL_HEIGHT, USE_ALL_WIDTH

Constructor Summary

protected

Manager(long style) Constructs a manager.

Method Summary

	void	add(Field field) Adds a field to this manager.
	void	delete(Field field) Removes a field from this manager.
	void	deleteAll() Removes all fields from this manager.
	void	deleteRange(int start, int count) Removes a range of fields from this manager.
	Field	getField(int index) Retrieves controlled field with specified index.
	int	getFieldAtLocation(int x, int y) Retrieves index of field under a particular point.
	int	getFieldCount() Retrieves number of fields controlled by this manager.
	Field	getFieldWithFocus() Retrieves controlled field with focus.
	int	getFieldWithFocusIndex() Retrieves index of controlled field with focus.
	void	getFocusRect(XYRect rect) Retrieves current extent of the focus.
	int	getHorizontalScroll() Returns current horizontal offset of scrolling region.
	Field	getLeafFieldWithFocus() Retrieves leaf field with focus.
	int	getVerticalScroll() Returns current vertical offset of scrolling region.
	int	getVirtualHeight() Returns this manager's virtual height.
	int	getVirtualWidth() Returns this manager's virtual width.
	int	getVisibleHeight() Retrieves height of this manager's visible region.
	int	getVisibleWidth() Retrieves width of this manager's visible region.
	void	insert(Field field, int index) Inserts a field into this manager.
	void	invalidate() Marks this entire manager as requiring repainting.
	protected void	invalidate(int x, int y, int width, int height) Marks a region as requiring repainting.
	boolean	isDirty() Determines if any controlled field is dirty.
	protected boolean	isDownArrowShown() Determines if downwards scroll arrow to be drawn.
	boolean	isFocusable() Verify that this manager accepts the focus.
	boolean	isMuddy() Determines if any controlled field is muddy.
	boolean	isSelecting() Determines if the field with focus is in selection mode.
	protected boolean	isUpArrowShown() Determines if upwards scroll arrow to be drawn.
	boolean	isValidLayout() Verifies this manager has a completed layout for its fields.
	protected boolean	keyChar(char c, int status, int time) Sends key generation event to the controlled field with focus.
	protected boolean	keyControl(char c, int status, int time) Sends key generation event to the controlled field with focus.
	protected boolean	keyDown(int keycode, int time) Sends key down event to the controlled field with focus.
	protected boolean	keyRepeat(int keycode, int time) Sends key repeat event to the controlled field with focus.
	protected boolean	keyStatus(int keycode, int time) Sends key status event to the controlled field with focus.
	protected boolean	keyUp(int keycode, int time) Sends key up event to the controlled field with focus.
	protected void	layout(int width, int height) Layout this manager's controlled fields.
	protected void	layoutChild(Field field, int width, int height) Prompts managed field to lay itself out.
	protected int	moveFocus(int amount, int status, int time) Called by the framework to move focus within this manager.
	protected void	moveFocus(int x, int y, int status, int time) Moves focus to an exact position within this manager.
	protected int	nextFocus(int direction, boolean alt) Returns the index of the next field that should be given focus.
	protected void	onFocus(int direction) Invoked by the framework when focus is gained.
	protected void	onUnfocus() Invoked by the framework when focus is lost.
	protected void	paint(Graphics graphics) Paints this manager's visible region.
	protected void	paintChild(Graphics graphics, Field field) Paints a controlled field.
	void	setDirty(boolean dirty) Cleans or dirties all controlled fields.
	boolean	setFocus(int x, int y, int status) Sets focus to exact position in current screen.
	void	setHorizontalQuantization(int horizontalQuanta) Sets this manager's horizontal quantization.
	void	setHorizontalScroll(int position) Sets this manager's horizontal scroll value.
	protected void	setPositionChild(Field field, int x, int y) Allows a Manager to set the position of one of its Fields.
	void	setScrollListener(ScrollChangeListener listener) Registers a listener for scroll changes.
	void	setVerticalQuantization(int verticalQuanta) Sets this manager's vertical quantization.
	void	setVerticalScroll(int position) Sets this manager's vertical scroll value.
	protected void	setVirtualExtent(int virtualWidth, int virtualHeight) Sets the virtual extent for this manager.
	protected abstract void	sublayout(int width, int height) Implements custom layout features for this manager.
	protected void	subpaint(Graphics graphics) Implements custom paint features for this manager.
	protected boolean	trackwheelClick(int status, int time) Dispatches trackwheel event to the controlled field with focus.
	protected boolean	trackwheelUnclick(int status, int time) Dispatches trackwheel released event to the controlled field with focus.

Methods inherited from class net.rim.device.api.ui.Field

drawFocus, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getChangeListener, getContextMenu, getCookie, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeft, getManager, getOriginal, getPreferredHeight, getPreferredWidth, getScreen, getStyle, getTop, getWidth, isEditable, isPasteable, isSelectable, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isVisible, makeContextMenu, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setChangeListener, setCookie, setEditable, setExtent, setFocus, setFocusListener, setFont, setMuddy, setPosition, updateLayout

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

VERTICAL_SCROLL_MASK

protected static final long VERTICAL_SCROLL_MASK

Bitfield mask of the vertical scroll style specifiers.

VERTICAL_SCROLL

public static final long VERTICAL_SCROLL

Manager style to turn on vertical scrolling.

If the manager's virtual height is larger than its visible height, the region scrolls vertically as required.

NO_VERTICAL_SCROLL

public static final long NO_VERTICAL_SCROLL

Manager will not support vertical scrolling.

HORIZONTAL_SCROLL_MASK

protected static final long HORIZONTAL_SCROLL_MASK

Bitfield mask of the horizontal scroll style specifiers.

HORIZONTAL_SCROLL

public static final long HORIZONTAL_SCROLL

Manager style to turn on horizontal scrolling.

If the manager's virtual width is larger than its visible width the region scrolls horizontally as required.

NO_HORIZONTAL_SCROLL

public static final long NO_HORIZONTAL_SCROLL

Manager will not support horizontal scrolling.

VERTICAL_SCROLLBAR_MASK

protected static final long VERTICAL_SCROLLBAR_MASK

Bitfield mask of the vertical scrollbar style specifiers.

VERTICAL_SCROLLBAR

public static final long VERTICAL_SCROLLBAR

Manager style to turn on vertical scrollbars.

NO_VERTICAL_SCROLLBAR

public static final long NO_VERTICAL_SCROLLBAR

Manager will not show vertical scrollbars.

HORIZONTAL_SCROLLBAR_MASK

protected static final long HORIZONTAL_SCROLLBAR_MASK

Bitfield mask of the horizontal scrollbar style specifiers.

HORIZONTAL_SCROLLBAR

public static final long HORIZONTAL_SCROLLBAR

Manager style to turn on horizontal scrollbars.

Note: this functionality not yet implemented.

NO_HORIZONTAL_SCROLLBAR

public static final long NO_HORIZONTAL_SCROLLBAR

Manager will not show horizontal scrollbars.

LEAVE_BLANK_SPACE

public static final long LEAVE_BLANK_SPACE

Manager style that leave blank space intact.

This style specifies that the layout update logic should not attempt to adjust the scroll offset to eliminate blank space.

NO_SCROLL_RESET

public static final long NO_SCROLL_RESET

Manager style to turn off resetting of scroll value when we leave the manager.

Since:

JDE 3.7.0

UPWARD

public static final int UPWARD

Indicates upward scroll direction.

DOWNWARD

public static final int DOWNWARD

Indicates downward scroll direction.

LEFTWARD

public static final int LEFTWARD

Indicates scroll direction is to the left.

RIGHTWARD

public static final int RIGHTWARD

Indicates scroll direction is to the right.

TOPMOST

public static final int TOPMOST

Indicates scrolling all the way to the top of the manager.

BOTTOMMOST

public static final int BOTTOMMOST

Indicates scrolling all the way to the bottom of the manager.

LEFTMOST

public static final int LEFTMOST

Indicates scrolling all the way to the left of the manager.

RIGHTMOST

public static final int RIGHTMOST

Indicates scrolling all the way to the right of the manager.

QUANTA_FONT

public static final int QUANTA_FONT

Indicates that the size of a quanta should be adjusted to the size of the current font on layout.

For vertical quantization, this is the font height. The value is reserved for future use with horizontal quantization.

See Also:

setHorizontalQuantization(int), setVerticalQuantization(int)

Constructor Detail

Manager

protected Manager(long style)

Constructs a manager.

Subclasses invoke this constructor in order to set the appropriate style bits for a new manager.

Parameters:

style - Style bits for this manager. The styles Field.FOCUSABLE, Field.NON_FOCUSABLE, Field.EDITABLE, Field.READONLY are ignored; these properties are controlled by the Manager's contents.

Throws:

IllegalArgumentException - Thrown if the parameter style specifies an invalid or undefined style.

Method Detail

add

public void add(Field field)

Adds a field to this manager.

Invoke this method to add a new field at the end of this manager's list of controlled fields.

Notice that only one manager is allowed to control any single field, and a field can never manage itself.

Parameters:

field - Field to add.

Throws:

IllegalStateException - If the field has already been added to a manager.

IllegalArgumentException - If the field is being added to itself.

Since:

JDE 3.7.0

delete

public void delete(Field field)

Removes a field from this manager.

Invoke this method to remove a field from this manager.

Parameters:

field - Field to remove.

Throws:

IllegalArgumentException - If the field to be deleted does not belong to this manager.

Since:

JDE 3.7.0

deleteAll

public void deleteAll()

Removes all fields from this manager.

Invoking this method has the same effect as

     manager.deleteRange( 0, manager.getFieldCount() )
 

deleteRange

public void deleteRange(int start,
                        int count)

Removes a range of fields from this manager.

Provide the index of the first field you want to delete, and the number of fields to delete.

Parameters:

start - Index at which to begin deletion.

count - Number of fields to delete.

Throws:

IndexOutOfBoundsException - If start or count are invalid.

Since:

JDE 3.7.0

getField

public Field getField(int index)

Retrieves controlled field with specified index.

Parameters:

index - Index of field to retrieve.

Returns:

Controlled field at specified index.

Throws:

IndexOutOfBoundsException - If index not valid.

Since:

JDE 3.7.0

getFieldWithFocus

public Field getFieldWithFocus()

Retrieves controlled field with focus.

Invoke this method to retrieve the field controlled by this manager that has the focus. Notice that the field returned may in fact be another manager.

Returns:

Controlled field with focus; if no field has the focus, returns null.

getFieldWithFocusIndex

public int getFieldWithFocusIndex()

Retrieves index of controlled field with focus.

Returns:

Index of controlled field with focus; if no field as the focus, returns -1.

getFocusRect

public void getFocusRect(XYRect rect)

Retrieves current extent of the focus.

Invoke this method to retrieve the extent of the current focus region. Notice that the coordinates expressed are local to this manager, and take scrolling into account (i.e. the coordinates are local to the manager's visible region, not the virtual region).

Overrides:

getFocusRect in class Field

Parameters:

rect - Rect to contain extent of focus.

Since:

JDE 3.7.0

getHorizontalScroll

public final int getHorizontalScroll()

Returns current horizontal offset of scrolling region.

Invoke this method to retrieve the current offset (from the left edge of this manager's virtual region) of the currently displayed part of the manager.

Returns:

Horizontal scroll value, in pixels.

getVerticalScroll

public final int getVerticalScroll()

Returns current vertical offset of scrolling region.

Invoke this method to retrieve the current offset (from the top edge of this manager's virtual region) of the currently displayed part of the manager.

Returns:

Vertical scroll offset, in pixels.

getVirtualHeight

public final int getVirtualHeight()

Returns this manager's virtual height.

The manager's virtual height is the entire height of the field that can be displayed, either at once or by scrolling.

Returns:

Virtual height of this manager, in pixels.

getVirtualWidth

public final int getVirtualWidth()

Returns this manager's virtual width.

The manager's virtual width is the entire width of the field that can be displayed, either at once or by scrolling.

Returns:

Virtual width of this manager, in pixels.

insert

public void insert(Field field,
                   int index)

Inserts a field into this manager.

Invoke this method to insert a new field into this manager's list of controlled fields. You provide the field to add, and the index position you wish the new field to occupy.

Parameters:

field - Field to insert.

index - Index at which to insert.

Throws:

IndexOutOfBoundsException - If index is less than zero or greater than getFieldCount().

IllegalStateException - If the field has already been added to a manager.

IllegalArgumentException - If the field is being added to itself.

Since:

JDE 3.7.0

isDirty

public boolean isDirty()

Determines if any controlled field is dirty.

Invoke this method to determine if any of this manager's controlled fields are dirty. A field is dirty if it has changed since the last time it was clean. A field is clean when it is first created, and also when explicitly cleaned by invoking setDirty(false).

Overrides:

isDirty in class Field

Returns:

True if the field has been changed since it was last clean.

isDownArrowShown

protected boolean isDownArrowShown()

Determines if downwards scroll arrow to be drawn.

A custom manager can override this method to provide precise control over the downwards scroll arrow. The framework can invoke this method at any time after performing a layout.

By default, this method returns true if the vertical scroll value plus this manager's visible height is less than this manager's virtual height.

Returns:

True if the arrow should be drawn; otherwise, false.

isMuddy

public boolean isMuddy()

Determines if any controlled field is muddy.

Invoke this method to determine if any of this manager's controlled fields are muddy. A field is muddy if it has changed and focus has not been moved or left the field since the change.

Overrides:

isMuddy in class Field

Returns:

True if at least one field is muddy; otherwise, false.

isSelecting

public boolean isSelecting()

Determines if the field with focus is in selection mode.

Overrides:

isSelecting in class Field

Returns:

True if the leaf field is currently in selection mode; otherwise, returns false.

isUpArrowShown

protected boolean isUpArrowShown()

Determines if upwards scroll arrow to be drawn.

A custom manager can override this method to provide precise control over the upwards scroll arrow. The framework can invoke this method at any time after performing a layout.

By default, this method returns true if the vertical scroll value is positive.

Returns:

True if the arrow should be drawn; otherwise, false.

isValidLayout

public final boolean isValidLayout()

Verifies this manager has a completed layout for its fields.

A manager's layout is valid after its screen has first been pushed onto the display stack.

Returns:

True if this manager has a completed layout for its controlled fields; otherwise, false.

layout

protected final void layout(int width,
                            int height)

Layout this manager's controlled fields.

Invoke this method to prompt this manager to lay out its controlled fields. If you extend manager to create a custom layout manager, you should implement the sublayout method, as this method invokes it.

Overrides:

layout in class Field

Parameters:

width - Width in pixels available to this manager.

height - Height in pixels available to this manager.

Since:

JDE 3.7.0

See Also:

sublayout(int, int)

layoutChild

protected final void layoutChild(Field field,
                                 int width,
                                 int height)

Prompts managed field to lay itself out.

Invoke this method to prompt this manager to tell one of its managed fields to lay itself out.

Parameters:

field - Field managed by this manager.

width - Width in pixels available to the field.

height - Height in pixels available to the field.

Since:

JDE 3.7.0

paint

protected void paint(Graphics graphics)

Paints this manager's visible region.

Invoke this method to prompt this manager to paint itself. if you extend manager to create a custom layout manager, you may want to implement the subpaint method, as this method invokes it.

This method also draws the focus indicator as required.

Overrides:

paint in class Field

Parameters:

graphics - Graphics object used for painting.

Since:

JDE 3.7.0

See Also:

subpaint(net.rim.device.api.ui.Graphics)

paintChild

protected final void paintChild(Graphics graphics,
                                Field field)

Paints a controlled field.

Invoke this method to paint a controlled field. This method ensures the graphics stack and drawing attributes are ready before invoking the paint method on the field you provide.

Parameters:

graphics - Graphics object used for painting.

field - Controlled field you wish to paint.

Since:

JDE 3.7.0

sublayout

protected abstract void sublayout(int width,
                                  int height)

Implements custom layout features for this manager.

If implementing a manager with custom layout features, you must override this method: the layout method invokes sublayout to do any custom layout handling.

Parameters:

width - Width available for this manager.

height - Height available for this manager.

Since:

JDE 3.7.0

See Also:

layout(int, int)

subpaint

protected void subpaint(Graphics graphics)

Implements custom paint features for this manager.

By default, this method paints all child fields, without regard to the clipping region.

If implementing a custom manager that has requirements for special paint handling, you can override this method for optimization. The layout method invokes subpaint to do any custom paint handling.

Parameters:

graphics - Graphics object used for painting.

Since:

JDE 3.7.0

getFieldCount

public int getFieldCount()

Retrieves number of fields controlled by this manager.

Returns:

Number of fields controlled by this manager.

getLeafFieldWithFocus

public Field getLeafFieldWithFocus()

Retrieves leaf field with focus.

Since managers can themselves control other managers, you can invoke this method to retrieve the leaf (bottom-most, non-manager) field that has the focus.

Overrides:

getLeafFieldWithFocus in class Field

Returns:

Leaf field with focus; otherwise, if no controlled field (directly or indirectly) has the focus, returns null.

invalidate

public void invalidate()

Marks this entire manager as requiring repainting.

Invoke this method to signal that this manager's entire region requires repainting.

Overrides:

invalidate in class Field

invalidate

protected void invalidate(int x,
                          int y,
                          int width,
                          int height)

Marks a region as requiring repainting.

Invoke this method to identify a region of this manager that requires repainting.

Overrides:

invalidate in class Field

Parameters:

x - Left edge of invalid rectangle.

y - Top edge of invalid rectangle.

width - Width of invalid rectangle.

height - Height of invalid rectangle.

Since:

JDE 3.7.0

isFocusable

public boolean isFocusable()

Verify that this manager accepts the focus.

Overrides:

isFocusable in class Field

Returns:

True if and only if any one of this manager's controlled fields (directly or indirectly) accepts the focus; otherwise, returns false.

moveFocus

protected int moveFocus(int amount,
                        int status,
                        int time)

Called by the framework to move focus within this manager.

This method searches fields in their index order, attempting to pass the focus on to the next available field.

The amount parameter specifies the number of index positions to hop over when moving the focus. Use a negative amount to move backwards in this manager's list of fields, a positive value to forwards. Note that some controlled fields may support more than one focus position (date fields, for example).

This method ignores the status and time parameters, but passes them on to the controlled fields. The status parameter should contain modifiers to the trackwheel roll event, such as modifier keys held while rolling, direction of roll, and so forth.

When the focus is moved from a controlled field, the onUnfocus handler method is invoked. Then, isFocusable is invoked on the next controlled field to determine if it accepts the focus.

As the focus passes over each field that accepts the focus, the amount parameter's absolute value is reduced by one, and that field is provided with the chance to respond to a new focus event. If the amount parameter's absolute value is still greater than zero, the focus passes on to the next field which accepts it.

If either end of this manager's field list is reached (the top for negative amount values, the bottom for positive amount values), either because of a large amount value, or because there are no fields left that accept the focus, this method returns the remaining amount that wasn't used up. Notice that the sign for the amount is preserved, to retain the direction indicator.

Overrides:

moveFocus in class Field

Parameters:

amount - If positive, move focus forward this many index positions; if negative, move focus backwards this many index positions.

status - Trackwheel event modifiers.

time - Ticks since device reset.

Returns:

Remaining scroll amount not used up, with the same sign as was originally provided with the amount parameter.

Since:

JDE 3.7.0

onFocus

protected void onFocus(int direction)

Invoked by the framework when focus is gained.

When the framework invokes this method, it starts either at the start of the manager's controlled field list, or the end (depending on the passed direction parameter), looking for a field to give the focus.

This method passes the focus to the first field it finds to accept it.

Overrides:

onFocus in class Field

Parameters:

direction - Specify 1 to search forward from the first controlled field in this manager's list. Specify -1 to search backward from the last controlled field in this manager's list.

Since:

JDE 3.7.0

onUnfocus

protected void onUnfocus()

Invoked by the framework when focus is lost.

Overrides:

onUnfocus in class Field

nextFocus

protected int nextFocus(int direction,
                        boolean alt)

Returns the index of the next field that should be given focus.

This method is called by the framework during a trackwheel focus move operation.

The direction parameter indicates which direction the focus is moving: a value of 1 indicates that the focus is moving forward (generally down and to the right), a value of -1 indicates that the focus is moving backwards (generally up and to the left).

Parameters:

direction - Direction the focus is moving within the field.

alt - True if ALT-rolling the trackwheel; otherwise, false.

Returns:

Index of the next field that should have focus, -1 if focus should leave the manager.

Throws:

IllegalArugmentException - If direction parameter has a value other than 1 or -1.

Since:

JDE 3.7.0

moveFocus

protected void moveFocus(int x,
                         int y,
                         int status,
                         int time)

Moves focus to an exact position within this manager.

Invoke this method to place the focus on a precise point within this manager's region.

This method ignores the status and time parameters, but passes them on to the controlled fields. The status parameter should contain modifiers to the trackwheel roll event, such as modifier keys held while rolling, direction of roll, and so forth.

Overrides:

moveFocus in class Field

Parameters:

x - Distance from left edge of virtual region.

y - Distance from top edge of virtual region.

status - Trackwheel event modifiers.

time - Ticks since device reset.

Since:

JDE 3.7.0

setFocus

public boolean setFocus(int x,
                        int y,
                        int status)

Sets focus to exact position in current screen.

This method retrieves a handle to the current screen, and then invokes setFocus on it (for the time parameter, it passes in a value of zero).

Parameters:

x - Distance from left edge of screen.

y - Distance from top edge of screen.

status - Modifiers when the trackwheel roll occured, from KeyPad.

Returns:

True if field under desired point accepts the focus; otherwise, returns false.

Since:

JDE 3.7.0

getFieldAtLocation

public int getFieldAtLocation(int x,
                              int y)

Retrieves index of field under a particular point.

Given a point in coordinates local to this manager's extent, this method returns the index of the controlled field under that point (or -1 if no field found under the specified point).

This method constrains its search to the extent of this manager: if you provide a coordinate outside this manager's extent, this method uses values along the edges of the extent as required.

By default, this method performs a linear search hit, testing each controlled field in turn. If you implement a manager, you can override this method to optimize its functionality.

Parameters:

x - Distance from left edge of manager's extent.

y - Distance from top edge of manager's extent.

Returns:

Index of the field; if no field found, return -1.

Since:

JDE 3.7.0

getVisibleHeight

public int getVisibleHeight()

Retrieves height of this manager's visible region.

Returns:

Height in pixels of the portion of this manager's region visible on the display.

getVisibleWidth

public int getVisibleWidth()

Retrieves width of this manager's visible region.

Returns:

Width in pixels of the portion of this manager's region visible on the display.

keyChar

protected boolean keyChar(char c,
                          int status,
                          int time)

Sends key generation event to the controlled field with focus.

If no controlled field has the focus, this method does nothing and returns false.

Overrides:

keyChar in class Field

Parameters:

c - Character generated.

status - Modifier key status.

time - Ticks since device reset.

Returns:

True if event was consumed; otherwise, returns false.

Since:

JDE 3.7.0

keyControl

protected boolean keyControl(char c,
                             int status,
                             int time)

Sends key generation event to the controlled field with focus.

If no controlled field has the focus, this method does nothing and returns false.

Overrides:

keyControl in class Field

Parameters:

c - Character generated.

status - Modifier key status.

time - Ticks since device reset.

Returns:

True if event was consumed; otherwise, returns false.

Since:

JDE 3.7.0

keyDown

protected boolean keyDown(int keycode,
                          int time)

Sends key down event to the controlled field with focus.

If no controlled field has the focus, this method does nothing and returns false.

Overrides:

keyDown in class Field

Parameters:

keycode - Code of key pressed.

time - Ticks since device reset.

Returns:

True if event was consumed; otherwise, returns false.

Since:

JDE 3.7.0

keyRepeat

protected boolean keyRepeat(int keycode,
                            int time)

Sends key repeat event to the controlled field with focus.

If no controlled field has the focus, this method does nothing and returns false.

Overrides:

keyRepeat in class Field

Parameters:

keycode - Code of key repeated.

time - Ticks since device reset.

Returns:

True if event was consumed; otherwise, returns false.

Since:

JDE 3.7.0

keyStatus

protected boolean keyStatus(int keycode,
                            int time)

Sends key status event to the controlled field with focus.

If no controlled field has the focus, this method does nothing and returns false.

Overrides:

keyStatus in class Field

Parameters:

keycode - Code of status key.

time - Ticks since device reset.

Returns:

True if event was consumed; otherwise, returns false.

Since:

JDE 3.7.0

keyUp

protected boolean keyUp(int keycode,
                        int time)

Sends key up event to the controlled field with focus.

If no controlled field has the focus, this method does nothing and returns false.

Overrides:

keyUp in class Field

Parameters:

keycode - Code of key released.

time - Ticks since device reset.

Returns:

True if event was consumed; otherwise, returns false.

Since:

JDE 3.7.0

setDirty

public void setDirty(boolean dirty)

Cleans or dirties all controlled fields.

Pass true to this method to dirty all this manager's controlled fields. Pass false to this method to clean all the controlled fields.

Overrides:

setDirty in class Field

Parameters:

dirty - True if dirtying the fields; false if cleaning them.

Since:

JDE 3.7.0

setHorizontalQuantization

public void setHorizontalQuantization(int horizontalQuanta)

Sets this manager's horizontal quantization.

The real horizontal size must be a multiple of your provided value.

Parameters:

horizontalQuanta - Horizontal quantization in pixels.

Since:

JDE 3.7.0

setHorizontalScroll

public void setHorizontalScroll(int position)

Sets this manager's horizontal scroll value.

Invoke this method to adjust the vertical scroll value for this manager. This method is not normally invoked as focus movement deals with scrolling automatically.

If you use this function to set the scroll value for a screen that is not on the display stack you must push the screen onto the stack first, before invoking this method.

Parameters:

position - New horizontal scroll position.

Throws:

IllegalStateException - If this manager is non scrollable.

IllegalArgumentException - If position is negative.

Since:

JDE 3.7.0

setPositionChild

protected final void setPositionChild(Field field,
                                      int x,
                                      int y)

Allows a Manager to set the position of one of its Fields.

Parameters:

field - Field managed by this manager.

x - Offset of the left of the field in its manager.

y - Offset of the top of the field in its manager.

Since:

JDE 3.7.0

setScrollListener

public void setScrollListener(ScrollChangeListener listener)

Registers a listener for scroll changes.

To unregister a scroll listener, pass null into this method.

Parameters:

listener - Object that listens for scroll changes.

Throws:

IllegalStateException - when there is already a listener set and your listener parameter is non-null.

Since:

JDE 3.7.0

setVerticalQuantization

public void setVerticalQuantization(int verticalQuanta)

Sets this manager's vertical quantization.

The real vertical size must be a multiple of your provided value.

Parameters:

verticalQanta - Veritcal quantization in pixels.

Since:

JDE 3.7.0

setVerticalScroll

public void setVerticalScroll(int position)

Sets this manager's vertical scroll value.

Invoke this method to adjust the vertical scroll value for this manager. This method is not normally invoked as focus movement deals with scrolling automatically.

If you use this function to set the scroll value for a screen that is not on the display stack you must push the screen onto the stack first, before invoking this method.

Parameters:

position - New vertical scroll position.

Throws:

IllegalStateException - If this manager is non scrollable.

IllegalArgumentException - If position is negative.

Since:

JDE 3.7.0

setVirtualExtent

protected final void setVirtualExtent(int virtualWidth,
                                      int virtualHeight)

Sets the virtual extent for this manager.

Use this method to specify the size of the area that child controls inhabit. If this extent is larger than the manager's visible area, scrolling is used to bring the extra area into view.

Subclasses should invoke this method when layout is called.

Parameters:

virtualWidth - Width of the manager's virtual extent.

virtualHeight - Height of the manager's virtual extent.

Since:

JDE 3.7.0

trackwheelClick

protected boolean trackwheelClick(int status,
                                  int time)

Dispatches trackwheel event to the controlled field with focus.

If no controlled field has the focus, this method does nothing and returns false.

Overrides:

trackwheelClick in class Field

Parameters:

status - Trackwheel event modifiers.

time - Ticks since device reset.

Returns:

True if event was consumed; otherwise, returns false.

Since:

JDE 3.7.0

trackwheelUnclick

protected boolean trackwheelUnclick(int status,
                                    int time)

Dispatches trackwheel released event to the controlled field with focus.

If no controlled field has the focus, this method does nothing and returns false.

Overrides:

trackwheelUnclick in class Field

Parameters:

status - Trackwheel event modifiers.

time - Ticks since device reset.

Returns:

True if event was consumed; otherwise, returns false.

Since:

JDE 3.7.0