Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS | NEXT CLASS	FRAMES | NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

Class gui.ObjectList

java.lang.Object
  |
  +--java.awt.Component
        |
        +--java.awt.Container
              |
              +--java.awt.Panel
                    |
                    +--gui.ObjectList

public class ObjectList

extends java.awt.Panel

ObjectList is a similar to awt.List, with the primary difference that list items can be general Objects, rather than being restricted to Strings. Along with this change, however, comes a number of additional capabilities, and possible customizations. Items in an ObjectList must be unique, and null is not allowed.

The List operations such as adding, deleting, selecting and replacing items are supported. In addition individual items may enabled or disabled (meaning they are `grayed out' and can't be selected). Items may be hidden or shown; hidden items are not visible, but keep their original position in the sequence. ObjectList can also support a hierarchical structure; children of an opened item are displayed, indented, below the parent. The necessary information is provided by subclassing and overriding the following methods:

public Object[] getChildren(Object item);
public Object getParent(Object item);

These return the children or parent objects respectively, out of which ObjectList will construct the necessary relationships.

The presentation of items can be also be customized. Items can be drawn graphically, and in different sizes, by overriding:

public Dimension paintItem(Graphics g, Object item);

It returns the size needed to display the item. The default is to draw a string obtained from getString(item). That later may also be overridden; it's default uses the toString() method.

When an item is clicked with the mouse, the select state is toggled and a LIST_SELECT or LIST_DESELECT event is posted. A double click on an item selects the item and posts an ACTION_EVENT event. The event's arg is the item. itemBounds(item) gives the position of the item in the window, so that the position of the mouse within the item can be determined from the event's x and y coordinates, allowing different operations to be associated with different parts of the item.

To facilitate `mouse documentation', ie. highlighting the selectable item under the mouse and/or showing descriptive text in an applet's status line, the MOUSE_MOVE and MOUSE_EXIT events are translated into new events. Events with id ObjectList.MOUSE_ENTER_ITEM, MOUSE_EXIT_ITEM and MOUSE_MOVE_ITEM are generated when the mouse enters, leaves or moves within an item (the latter only being useful when items have different `parts'). The methods highlightRect and itemBounds may be useful in handling these events.

See Also:

getChildren, getParent, paintItem, getString, Serialized Form

Field Summary

static int	ALWAYS Indicates a scrollbar should always be displayed.
static int	IFNEEDED Indicates a scrollbar should be displayed only if needed.
static int	MOUSE_ENTER_ITEM id for Events which call for highlighting an item.
static int	MOUSE_EXIT_ITEM id for Events which call for un-highlighting an item.
static int	MOUSE_MOVE_ITEM id for Events which call for a change in highlighting due to mouse movement within an item.
static int	NEVER Indicates a scrollbar should never be displayed.

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Constructor Summary

ObjectList(int nColumns, int nRows)
Creates a new ObjectList of nColumns*nRows characters and not allowing multiple selections.

ObjectList(int nColumns, int nRows, boolean multipleSelections)
Creates a new ObjectList of nColumns*nRows characters and specifying whether multiple selections are allowed or not.

Method Summary

void	addItem(java.lang.Object item) Adds item as a root node at the end.
void	addItem(java.lang.Object item, int index) Adds item as a root node at a particular position in the list.
void	addItems(java.lang.Object[] items, boolean enabled, boolean hidden) Adds a sequence of items as roots at the end of object list.
void	addItems(java.lang.Object[] items) Adds a sequence of items as roots at the end of object list.
boolean	allowsMultipleSelections() Returns true if this list allows multiple selections.
void	clear() Clears the list.
void	close(java.lang.Object item) Close this item, hiding its children (if any).
void	delItem(java.lang.Object item) Delete a root item from the list.
void	deselectAll() Deselect all selected items.
void	deselect(java.lang.Object item) Deselects the item.
void	disable(java.lang.Object item) Disable this item.
boolean	duplicatesIgnored() Returns whether duplicated items inserted into the list are ignored.
void	enable(java.lang.Object item) Enable this item.
void	enable(java.lang.Object item, boolean value) Enable or Disable this item according to value.
java.lang.Object[]	getChildren(java.lang.Object item) Get the children associated with item.
int	getIndentation(int i) Get the indentation (in pixels) for each level of the hierarchy.
java.lang.Object	getParent(java.lang.Object item) Get the parent associated with item.
java.lang.Object	getSelectedItem() Get the selected item or null if no item is selected.
java.lang.Object[]	getSelectedItems() Returns the selected items on the list.
java.lang.String	getString(java.lang.Object item) Return a descriptive string for item.
int	getXScrolling() Returns the code for whether X (horizontal) scroll bar should appear.
int	getYScrolling() Returns the code for whether Y (vertical) scroll bar should appear.
boolean	handleEvent(java.awt.Event e) Event handler: handles item selection and mouse documentation.
void	hide(java.lang.Object item) Hide this item.
void	highlightRect(int x, int y, int width, int height) Draws a highlighting rectangle, using XOR, with the given position and size.
void	highlightRect(java.awt.Rectangle r) Draws a highlighting rectangle, using XOR.
void	ignoreDuplicates(boolean value) Specifies whether duplicated items inserted into the list should be ignored instead of signalling an error.
java.awt.Insets	insets()
boolean	isEnabled() What's going on with `inheritance' of enabled/disabled?
boolean	isEnabled(java.lang.Object item) Is this item enabled?
boolean	isOpenable(java.lang.Object item) Is this item able to be opened?
boolean	isOpen(java.lang.Object item) Is this item opened?
boolean	isSelected(java.lang.Object item) Returns true if the item has been selected; false otherwise.
boolean	isShowing(java.lang.Object item) Is this item showing (visible and parent is open and showing) ?
boolean	isVisible(java.lang.Object item) Is this item visible?
java.awt.Rectangle	itemBounds(java.lang.Object item) Returns the bounding rectangle of the item on the ObjectList.
void	layout() layout the panel.
void	makeVisible(java.lang.Object item) Scroll the panel to force item (and its children) to be visible.
java.awt.Dimension	minimumSize() Returns the minimum dimensions needed for the object list.
void	open(java.lang.Object item) Open this item, revealing its children (if any).
java.awt.Dimension	paintItem(java.awt.Graphics g, java.lang.Object item) Paint item at the current position in g.
void	paint(java.awt.Graphics g) Paint the display.
java.awt.Dimension	preferredSize() Returns the preferred dimensions needed for the object list.
void	replaceItem(java.lang.Object newItem, java.lang.Object oldItem) Replaces the root oldItem with newItem.
void	select(java.lang.Object item) Selects the item.
void	setIndentation(int i) Set the indentation (in pixels) for each level of the hierarchy.
void	setMultipleSelections(boolean v) Sets whether this list should allow multiple selections or not.
void	setXScrolling(int xscrolling) Specify whether x scrollbars should be displayed always, never or only when needed.
void	setYScrolling(int yscrolling) Specify whether y scrollbars should be displayed always, never or only when needed.
void	show(java.lang.Object item) Show this item.
void	show(java.lang.Object item, boolean value) Show or Hide this item according to value.
void	update(java.awt.Graphics g) Update the display.

Methods inherited from class java.awt.Panel

addNotify

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, addNotify, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponentAt, getComponentAt, getComponent, getComponentCount, getComponents, getInsets, getLayout, getMaximumSize, getMinimumSize, getPreferredSize, insets, invalidate, isAncestorOf, layout, list, list, locate, minimumSize, paintComponents, paint, paramString, preferredSize, printComponents, print, processContainerEvent, processEvent, removeAll, remove, remove, removeContainerListener, removeNotify, setLayout, update, validate, validateTree

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, deliverEvent, disable, disableEvents, dispatchEvent, doLayout, enable, enable, enableEvents, enableInputMethods, firePropertyChange, getAlignmentX, getAlignmentY, getBackground, getBounds, getBounds, getColorModel, getComponentAt, getComponentAt, getComponentOrientation, getCursor, getDropTarget, getFont, getFontMetrics, getForeground, getGraphics, getHeight, getInputContext, getInputMethodRequests, getLocale, getLocation, getLocation, getLocationOnScreen, getMaximumSize, getMinimumSize, getName, getParent, getPeer, getPreferredSize, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, invalidate, isDisplayable, isDoubleBuffered, isEnabled, isFocusTraversable, isLightweight, isOpaque, isShowing, isValid, isVisible, keyDown, keyUp, layout, list, list, list, list, list, locate, location, lostFocus, minimumSize, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, paint, paramString, postEvent, preferredSize, prepareImage, prepareImage, printAll, print, processComponentEvent, processEvent, processFocusEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, remove, removeComponentListener, removeFocusListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, reshape, resize, resize, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFont, setForeground, setLocale, setLocation, setLocation, setName, setSize, setSize, setVisible, show, show, size, toString, transferFocus, update, validate

Methods inherited from class java.lang.Object

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

Field Detail

MOUSE_ENTER_ITEM

public static final int MOUSE_ENTER_ITEM

id for Events which call for highlighting an item.

MOUSE_EXIT_ITEM

public static final int MOUSE_EXIT_ITEM

id for Events which call for un-highlighting an item.

MOUSE_MOVE_ITEM

public static final int MOUSE_MOVE_ITEM

id for Events which call for a change in highlighting due to mouse movement within an item.

IFNEEDED

public static final int IFNEEDED

Indicates a scrollbar should be displayed only if needed.

ALWAYS

public static final int ALWAYS

Indicates a scrollbar should always be displayed.

NEVER

public static final int NEVER

Indicates a scrollbar should never be displayed.

Constructor Detail

ObjectList

public ObjectList(int nColumns,
                  int nRows)

Creates a new ObjectList of nColumns*nRows characters and not allowing multiple selections.

ObjectList

public ObjectList(int nColumns,
                  int nRows,
                  boolean multipleSelections)

Creates a new ObjectList of nColumns*nRows characters and specifying whether multiple selections are allowed or not.

Parameters:

nColumns - the number of columns in characters.

nRows - the number of rows of items.

multipleSelections - if true then multiple selections are allowed.

Method Detail

getIndentation

public int getIndentation(int i)

Get the indentation (in pixels) for each level of the hierarchy.

setIndentation

public void setIndentation(int i)

Set the indentation (in pixels) for each level of the hierarchy.

setXScrolling

public void setXScrolling(int xscrolling)

Specify whether x scrollbars should be displayed always, never or only when needed.

getXScrolling

public int getXScrolling()

Returns the code for whether X (horizontal) scroll bar should appear.

setYScrolling

public void setYScrolling(int yscrolling)

Specify whether y scrollbars should be displayed always, never or only when needed.

getYScrolling

public int getYScrolling()

Returns the code for whether Y (vertical) scroll bar should appear.

duplicatesIgnored

public boolean duplicatesIgnored()

Returns whether duplicated items inserted into the list are ignored.

ignoreDuplicates

public void ignoreDuplicates(boolean value)

Specifies whether duplicated items inserted into the list should be ignored instead of signalling an error.

insets

public java.awt.Insets insets()

Overrides:

insets in class java.awt.Container

preferredSize

public java.awt.Dimension preferredSize()

Returns the preferred dimensions needed for the object list.

Overrides:

preferredSize in class java.awt.Container

minimumSize

public java.awt.Dimension minimumSize()

Returns the minimum dimensions needed for the object list.

Overrides:

minimumSize in class java.awt.Container

layout

public void layout()

layout the panel.

Overrides:

layout in class java.awt.Container

isEnabled

public boolean isEnabled()

What's going on with `inheritance' of enabled/disabled?

Overrides:

isEnabled in class java.awt.Component

addItem

public void addItem(java.lang.Object item)

Adds item as a root node at the end.

addItem

public void addItem(java.lang.Object item,
                    int index)

Adds item as a root node at a particular position in the list.

addItems

public void addItems(java.lang.Object[] items,
                     boolean enabled,
                     boolean hidden)

Adds a sequence of items as roots at the end of object list. They all are enabled and hidden according to the two given flags.

addItems

public void addItems(java.lang.Object[] items)

Adds a sequence of items as roots at the end of object list.

replaceItem

public void replaceItem(java.lang.Object newItem,
                        java.lang.Object oldItem)

Replaces the root oldItem with newItem.

clear

public void clear()

Clears the list.

delItem

public void delItem(java.lang.Object item)

Delete a root item from the list.

getSelectedItem

public java.lang.Object getSelectedItem()

Get the selected item or null if no item is selected.

getSelectedItems

public java.lang.Object[] getSelectedItems()

Returns the selected items on the list.

select

public void select(java.lang.Object item)

Selects the item.

deselect

public void deselect(java.lang.Object item)

Deselects the item.

deselectAll

public void deselectAll()

Deselect all selected items.

isSelected

public boolean isSelected(java.lang.Object item)

Returns true if the item has been selected; false otherwise.

allowsMultipleSelections

public boolean allowsMultipleSelections()

Returns true if this list allows multiple selections.

setMultipleSelections

public void setMultipleSelections(boolean v)

Sets whether this list should allow multiple selections or not.

isEnabled

public boolean isEnabled(java.lang.Object item)

Is this item enabled?

enable

public void enable(java.lang.Object item)

Enable this item. A disabled item is typically grayed out; it is not available for selection.

disable

public void disable(java.lang.Object item)

Disable this item. A disabled item is typically grayed out; it is not available for selection.

enable

public void enable(java.lang.Object item,
                   boolean value)

Enable or Disable this item according to value.

getChildren

public java.lang.Object[] getChildren(java.lang.Object item)

Get the children associated with item. This method is intended to be overridden by a subclass: It should return an array of the children objects of item; the default returns null (no children).

getParent

public java.lang.Object getParent(java.lang.Object item)

Get the parent associated with item. This method is intended to be overridden by a subclass: It should return the parent object of item; the default returns null (ie. a top level item).

isOpen

public boolean isOpen(java.lang.Object item)

Is this item opened?

isOpenable

public boolean isOpenable(java.lang.Object item)

Is this item able to be opened?

open

public void open(java.lang.Object item)

Open this item, revealing its children (if any).

close

public void close(java.lang.Object item)

Close this item, hiding its children (if any).

isVisible

public boolean isVisible(java.lang.Object item)

Is this item visible?

isShowing

public boolean isShowing(java.lang.Object item)

Is this item showing (visible and parent is open and showing) ?

show

public void show(java.lang.Object item)

Show this item.

hide

public void hide(java.lang.Object item)

Hide this item.

show

public void show(java.lang.Object item,
                 boolean value)

Show or Hide this item according to value.

makeVisible

public void makeVisible(java.lang.Object item)

Scroll the panel to force item (and its children) to be visible.

update

public void update(java.awt.Graphics g)

Update the display.

Overrides:

update in class java.awt.Container

paint

public void paint(java.awt.Graphics g)

Paint the display.

Overrides:

paint in class java.awt.Container

handleEvent

public boolean handleEvent(java.awt.Event e)

Event handler: handles item selection and mouse documentation.

Overrides:

handleEvent in class java.awt.Component

paintItem

public java.awt.Dimension paintItem(java.awt.Graphics g,
                           java.lang.Object item)

Paint item at the current position in g. This method may be overridden by a subclass. The graphics object has already been prepared as to position and colors according to selection and enabling and the background has already been cleared. The default draws the string returned by getString. Note that this method may be called with g = null in order to determine the size of the node; in this case nothing should be drawn.

See Also:

getString

getString

public java.lang.String getString(java.lang.Object item)

Return a descriptive string for item. This method may be overridden by a subclass. The string is used by the default paintItem and in mouse documentation. The default is to use toString().

itemBounds

public java.awt.Rectangle itemBounds(java.lang.Object item)

Returns the bounding rectangle of the item on the ObjectList.

highlightRect

public void highlightRect(int x,
                          int y,
                          int width,
                          int height)

Draws a highlighting rectangle, using XOR, with the given position and size.

highlightRect

public void highlightRect(java.awt.Rectangle r)

Draws a highlighting rectangle, using XOR.