borland Packages  Class Hierarchy  jbcl.view Package  Index 

ListView component

java.lang.Object
   +----java.awt.Component
           +----java.awt.Container
                   +----com.sun.java.swing.JComponent
                           +----com.sun.java.swing.JScrollPane
                                   +----borland.jbcl.view.ListView
                                           +----borland.jbcl.control.ListControl

About the ListView component

Variables  Constructors  Properties  Methods  Event Listeners

Implements VectorView, Accessible, ScrollPaneConstants, ImageObserver, MenuContainer, Serializable

The ListView component provides much of the behavior and attributes of a list control. JBCL's ListControl extends ListView. It requires a VectorModel data model and a VectorViewManager view manager.

The itemHeight property specifies the height of each item in the list view while the itemWidth property specifies the width of each item. These properties work in conjunction with the uniformHeight and uniformWidth properties. For example, setting itemHeight to a value sets uniformHeight to true, meaning that each item has the height specified in itemHeight. If no itemHeight is specified and uniformHeight is true, the height for each item is calculated to be height of the first item in the list. If uniformHeight is false, each item can have a different height.

To specify the margins around each item in the list, set the itemMargins property.

To align the items in the view, set the alignment property. The value of topIndex determines which item appears at the top of the list. You can determine if scrolling within the view is smooth and continuous or scrolling "snaps" to each item in the list view with the snapOrigin property. The value of showFocus determines whether the item that has the subfocus in the list has a focus rectangle around it. Setting showRollover to true means that the item that has the mouse cursor over it is highlighted.

The value of subfocus identifies the item that has the current subfocus in the list. selection provides access to the set of selected items in the list view.

The readOnly property determines whether the items in the list can be edited. The startEdit() begins an edit session on an item and endEdit() and endSafeEdit() methods end an edit session. When an edit session is underway, the editing property is true. The value of editInPlace enables or disables the editing of an items in the list. When the autoEdit property is true, the user can begin editing an item by typing; otherwise, the user must press F2 or Ctrl+Enter to begin an edit session.

Several properties and methods control how painting takes place within the view. If directDraw is true, drawing bypasses the AWT paint queue and occurs directly. Setting doubleBuffer to true reduces flick during painting. To make mass changes to the list without waiting for repainting after each change, use the batchMode property. The getItemRectangle() method retrieves the rectangle that surrounds the item to be repainted. The repaintItem() method paints a specified item and the repaintItems() method paints all the items in the list.

For an example that uses ListView, see the project file ListView.jpr located in the jbuilder\samples\borland\samples\jbcl\listview directory of your JBuilder installation.


ListView variables

Variables implemented in com.sun.java.swing.JComponent

Variables implemented in com.sun.java.swing.JScrollPane

Variables implemented in java.awt.Component

ListView constructors

ListView properties

*Read-only properties **Write-only properties

Properties implemented in this class

Properties implemented in com.sun.java.swing.JComponent

Properties implemented in com.sun.java.swing.JScrollPane

Properties implemented in java.awt.Component

Properties implemented in java.awt.Container

Properties implemented in java.lang.Object

ListView methods

Methods implemented in this class

Methods implemented in com.sun.java.swing.JComponent

Methods implemented in com.sun.java.swing.JScrollPane

Methods implemented in java.awt.Component

Methods implemented in java.awt.Container

Methods implemented in java.lang.Object

ListView event listeners


ListView constructors

ListView()

  public ListView()

Constructs a ListView component with default property values.


ListView properties

alignment

 public int getAlignment()
 public void setAlignment(int alignment)
Specifies the alignment (right, left, center) of the items in the list. Accepted values for the align argument are listed in borland.jbcl.util.Alignment where they are defined.

autoAppend

 public boolean isAutoAppend()
 public void setAutoAppend(boolean autoAppend)
Enables or disables automatic item appending at the end of the list. By default, this property is false, and a user must insert rows with the Insert key or by navigating to the end of the list and pressing Ctrl+Down. Setting this property to true allows the user to append new items by navigating past the last item.

autoEdit

 public boolean isAutoEdit()
 public void setAutoEdit(boolean autoEdit)
Enables or disables automatic item editing in the list. By default, this property is true, and a user can edit values in any item on the list by typing a character on the keyboard. If set to false, the user must press F2 or Ctrl+Enter, or double-click to start an edit session. By default, this property is true.

background

 public void setBackground(java.awt.Color color)
Determines the background color of the list view. Specify a java.awt.Color object for the color.

batchMode

 public boolean isBatchMode()
 public void setBatchMode(boolean batchMode)
Enables or disables all painting in the list. This is used for programmatic mass updates to the list's model, selection, or other related objects, without triggering repaint messages. If true, painting is disabled; if false, painting occurs with each change to the list.

coreComponent

 public Component getCoreComponent()
Returns the contained ListCore (non-public) class instance as a Component.

dataToolTip

 public boolean isDataToolTip()
 public void setDataToolTip(boolean dataToolTip)
The dataToolTip property enables/disables the automatic tooltip mechanism to display the contents of the model (as text) in a tooltip window when the mouse is floating over the field. By default, this property is false. If dataToolTip is set to true, the text stored in the toolTipText property is discarded.

dragSubfocus

 public boolean isDragSubfocus()
 public void setDragSubfocus(boolean dragSubfocus)
Enables or disables dragging of the subfocus item when dragging the mouse pointer over the list (with the mouse button pressed). By default, this property is true.

editing

 public boolean isEditing()
A read-only property that returns true if an item is currently being edited in the list.

editInPlace

 public boolean isEditInPlace()
 public void setEditInPlace(boolean editInPlace)
Enables or disables item editing in the list. By default, this property is true, and a user can edit values in any item on the list. If set to false, the vector data cannot by modified by the user - except through programmatic access to the list's model.

editor

 public ItemEditor getEditor()
Returns the item editor being used or null if the list is not being edited.

enabled

 public void setEnabled(boolean enabled)
Determines whether the view is enabled or disabled. If true, the control is enabled; if false, it isn't. When disabled, the view appears dimmed and cannot receive focus.

font

 public void setFont(java.awt.Font font)
Sets the java.awt.Font to use in the list view.

foreground

 public void setForeground(java.awt.Color color)
Sets the foreground in the list view to the specified java.awt.Color.

growEditor

 public boolean isGrowEditor()
 public void setGrowEditor(boolean growEditor)
The growEditor property enables/disables the automatic sizing of an item's item editor. In some look and feel settings, the item editors must grow vertically to properly edit the data. By default, this property is set to true.

itemHeight

 public int getItemHeight()
 public void setItemHeight(int newHeight)
When set, the view need not scan through the entire list of items, examining the height of each, to determine which item has been clicked, selected, or edited. Instead, it calculates item vertical location based on the value of itemHeight. Setting itemHeight sets uniformHeight to true. The height is expressed in pixels.

itemMargins

 public Insets getItemMargins()
 public void setItemMargins(java.awt.Insets margins)
Specifies the space allowed between the actual edge of the item and the edge of its region allotted in the list. The Insets object that specifies the margins around the items in the view.

itemWidth

 public int getItemWidth()
 public void setItemWidth(int newWidth)
When set, the view need not scan through the entire list of items, examining the width of each, to determine which item has been clicked, selected, or edited. Instead, it calculates item horizontal location based on the value of itemWidth. Setting itemWidth sets uniformWidth to true. The width is expressed in pixels.

model

 public VectorModel getModel()
 public void setModel(borland.jbcl.model.VectorModel vm)
Defines the VectorModel that this list is displaying data from. If the current model is an instance of WritableVectorModel, an external user can get access to it using getWriteModel().

opaque

 public boolean isOpaque()
 public void setOpaque(boolean opaque)
Controls the grid's opacity. If a texture is set, the opaque property is automatically set to true, which is the default value.

postOnEndEdit

 public boolean isPostOnEndEdit()
 public void setPostOnEndEdit(boolean post)
Specifies whether to write changes to the model immediately upon the end of an edit. If true, the item is posted immediately; if false, it isn't. By default, postOnEndEdit is true.

preferredSize

 public Dimension getPreferredSize()
Specifies the size that you would prefer layout managers to use for this field.

readOnly

 public boolean isReadOnly()
 public void setReadOnly(boolean ro)
Used when you want the model to be treated as a read-only model though it is actually a WritableVectorModel. This is commonly used to allow users to browse, but not edit, normally writable vectors of data.

selection

 public WritableVectorSelection getSelection()
 public void setSelection(borland.jbcl.model.WritableVectorSelection vs)
Defines a WritableVectorSelection manager. This allows multiple vector viewers to share the same selection pool, and for the list to handle selection in a generic manner so that users can plug in their own implemention of a selection manager to have custom selection behavior.

showFocus

 public boolean isShowFocus()
 public void setShowFocus(boolean focus)
Specifies whether the component displays a dotted rectangle that indicates the subfocus location. If true, a focus rectangle is visible; if false, it isn't.

showRollover

 public boolean isShowRollover()
 public void setShowRollover(boolean showRollover)
Enables or disables the repainting of the rollover item. The rollover item is the item that currently has the mouse cursor floating over it. If showRollover is true, the item the mouse cursor is over is highlighted.

If an ItemPainter plugged into the list ignores the ROLLOVER bit, this property will have no effect. By default, showRollover is true.

snapOrigin

 public boolean isSnapOrigin()
 public void setSnapOrigin(boolean snapOrigin)
Controls whether or not the list will automatically snap the scroll position to align the top item with the top edge of the list. If set to false, the list will not snap the scroll position, and it will scroll smoothly with changes to the subfocus item. By default, this property is true.

subfocus

 public int getSubfocus()
 public void setSubfocus(int index)
Specifies the index position of the item that has subfocus within the component.

texture

 public Image getTexture()
 public void setTexture(java.awt.Image texture)
Defines the image that is tiled repeatedly, producing a background texture.

toolTipText

 public String getToolTipText()
 public void setToolTipText(java.lang.String text)
Determines the text that appears in the tool tip window. Specify the text as the value of the text parameter.

topIndex

 public int getTopIndex()
 public void setTopIndex(int index)
Represents which item index is at the top-most of the visible items in the list. Setting this property doesn't move the subfocus item within the list, but scrolls the list to the appropriate position.

uniformHeight

 public boolean isUniformHeight()
 public void setUniformHeight(boolean uniformHeight)
Determines whether the items in the list share a single uniform height. Setting uniformHeight to true allows the view to calculate item vertical location based on the value of itemHeight (or the height of the first item) rather than scanning throught the entire list of items.

If uniformHeight is true, and itemHeight is null (has not been set), the view assumes that the all items have the height of the first item in the list.

If this property is false, items in the list can differ in height.

uniformWidth

 public boolean isUniformWidth()
 public void setUniformWidth(boolean uniformWidth)
Determines whether the items in the list share a single uniform width. Setting uniformWidth to true allows the view to calculate item horizontal location based on the value of itemWidth (or the width of the first item) rather than scanning throught the entire list of items.

If uniformWidth is true, and itemWidth is null (has not been set), the view assumes that the all items have the width of the first item in the list.

If this property is false, items in the list can differ in width.

viewManager

 public VectorViewManager getViewManager()
 public void setViewManager(borland.jbcl.model.VectorViewManager vvm)
The viewManager property defines the VectorViewManager that manages the ItemPainters and ItemEditors for the list view.

writeModel

 public WritableVectorModel getWriteModel()
Returns the model for this list view.

ListView methods

addNotify()

  public void addNotify()

Overrides: java.awt.Container.addNotify()

checkParentWindow()

  public void checkParentWindow()

createDefaultModel()

  protected VectorModel createDefaultModel()
Creates a BasicVectorContainer.

createDefaultSelection()

  protected WritableVectorSelection createDefaultSelection()
Creates a SingleVectorSelection.

createDefaultViewManager()

  protected VectorViewManager createDefaultViewManager()
Creates a BasicViewManager.

endEdit()

  public void endEdit()
Ends the current edit session (if any). If the value has been modified, it will be posted if postOnEndEdit is set to true (the default). If postOnEndEdit is false, the edit session will be terminated without saving the changes to the item's value.

endEdit(boolean)

  public void endEdit(boolean post)
Ends the editing of an item, marking the item editor for garbage collection. Writes the change to the model if post is true.

getItemRect(int)

  public Rectangle getItemRect(int index)
Returns the Rectangle (in pixels) that bounds the item at the specified index. Coordinates are relative to the entire scrollable region inside of the ListView. Use getScrollPosition() and getViewportSize() to calculate relative point positions to external components.

Returns the bounding rectangle of the item.

Parameters:

index
The item index that you want the rectangle for.

hasFocus()

  public boolean hasFocus()

Overrides: com.sun.java.swing.JComponent.hasFocus() Determines whether the list has the focus. If it returns true, the grid has the focus.

hitTest(int)

  public int hitTest(int y)
Returns the index of the item at the Y coordinate specified. Coordinates are relative to the entire scrollable region inside of the ListView. Use getScrollPosition() and getViewportSize() to calculate relative point positions to external components.

Returns the hit index, or -1 if nothing was hit.

Parameters:

y
The y location.

repaintItem(int)

  public void repaintItem(int index)
Repaints the item at the passed index.

Parameters:

index
The index that you want repainted.

repaintItems()

  public void repaintItems()
Repaints all items in the list.

requestFocus()

  public void requestFocus()

Overrides: com.sun.java.swing.JComponent.requestFocus()

safeEndEdit()

  public void safeEndEdit()
Ends the current edit session (if any), catching any exceptions. If the value has been modified, it will be posted if postOnEndEdit is set to true (the default). If postOnEndEdit is false, the edit session will be terminated without saving the changes to the item's value.

safeEndEdit(boolean)

  public void safeEndEdit(boolean post)
Ends the current edit session (if any), catching any exceptions. If the value has been modified, it will be posted if post is set to true. If post is false, the edit session will be terminated without saving the changes to the item's value.

Parameters:

post
If true, edits are posted; if false, edits are not posted.

startEdit(int)

  public void startEdit(int index)
Starts an edit session at 'index'. If editInPlace is false or if readOnly is true, this method is a no-op.

Parameters:

index
The item index to start the edit session at.

updateUI()

  public void updateUI()

Overrides: com.sun.java.swing.JScrollPane.updateUI() Updates the user interface of the view in preparation for painting.


ListView event listeners

This component is a source for the following event sets. For information on the standard AWT event sets, see Standard Java events. For information on the JBCL event sets, see Events in JBCL.

action

 public void addActionListener(java.awt.event.ActionListener l)
 public void removeActionListener(java.awt.event.ActionListener l)

ancestor

 public void addAncestorListener(com.sun.java.swing.event.AncestorListener )
 public void removeAncestorListener(com.sun.java.swing.event.AncestorListener )

component

 public synchronized void addComponentListener(java.awt.event.ComponentListener )
 public synchronized void removeComponentListener(java.awt.event.ComponentListener )

container

 public synchronized void addContainerListener(java.awt.event.ContainerListener )
 public void removeContainerListener(java.awt.event.ContainerListener )

customItem

 public void addCustomItemListener(borland.jbcl.view.CustomItemListener l)
 public void removeCustomItemListener(borland.jbcl.view.CustomItemListener l)

focus

 public void addFocusListener(java.awt.event.FocusListener l)
 public void removeFocusListener(java.awt.event.FocusListener l)

key

 public void addKeyListener(java.awt.event.KeyListener l)
 public void removeKeyListener(java.awt.event.KeyListener l)

model

 public void addModelListener(borland.jbcl.model.VectorModelListener listener)
 public void removeModelListener(borland.jbcl.model.VectorModelListener listener)

mouse

 public void addMouseListener(java.awt.event.MouseListener l)
 public void removeMouseListener(java.awt.event.MouseListener l)

mouseMotion

 public void addMouseMotionListener(java.awt.event.MouseMotionListener l)
 public void removeMouseMotionListener(java.awt.event.MouseMotionListener l)

propertyChange

 public synchronized void addPropertyChangeListener(java.beans.PropertyChangeListener )
 public synchronized void removePropertyChangeListener(java.beans.PropertyChangeListener )

selection

 public void addSelectionListener(borland.jbcl.model.VectorSelectionListener listener)
 public void removeSelectionListener(borland.jbcl.model.VectorSelectionListener listener)

subfocus

 public void addSubfocusListener(borland.jbcl.model.VectorSubfocusListener listener)
 public void removeSubfocusListener(borland.jbcl.model.VectorSubfocusListener listener)

vetoableChange

 public synchronized void addVetoableChangeListener(java.beans.VetoableChangeListener )
 public synchronized void removeVetoableChangeListener(java.beans.VetoableChangeListener )