3.4.5 - Split List - JdlSplitList

John W. Campbell

3.4.5.1 Introduction

This class provides a selectable list which may be split into vertical columns with movable boundaries. The list has a title line and is always vertically scrollable. It can also be used for the simpler case with just a single column. Additional settings allow for a selection of drag-and-drop and copy-and-paste options. If required a horizontal scroll bar may also be used. It should be noted that when selected items are dragged or copied from the split list, a single string is transferred with newline (\n) characters between each item and tab (\t) characters between the text from each columns. Any special characters (\t \n \r \f) within the text of a column are replaced by single spaces. A similar reverse procedure applies except that any spaces within the input string are left unchanged.

Class, fields, constructor and methods:

Class Details
Accessible Fields
Constructor
Operational Methods
Drag and Drop Methods
Standard Positioning and Sizing
Add/Remove Action Listener
Overriden Superclass Methods

3.4.5.2 Class Details

Package:
Jdl.JdlView;
Class name:
JdlSplitList
Class definition:
public class JdlSplitList
Extends:
JdlDrawPanel
Implements:
ActionListener
MouseListener
ListSelectionListener
DropTargetListener
KeyListener
ChangeListener
JdlViewObject
Actions:
An action event will be generated when a list item or items is/are selected or de-selected. The associated object is the string "Selection made". An action event will also be generated when the list contents are modified by drag and drop or paste actions. The associated objects are the strings "Items moved" (items moved via internal drag and drop), "Items removed" (items removed after a drag (and drop) out from the split list, "Items dropped" (items added via a drop from an external drag and drop) or "Items pasted" (items added via a paste).

3.4.5.3 Accessible Fields

The following accessible fields have been defined:

static final long serialVersionUID
public final static int PREFERRED
Size Constraint: preferred size.
public final static int FREE
Size/Location Constraint: free.
public final static int NO_SELECTION
Selection mode: no selection.
public final static int SINGLE_SELECTION
Selection mode: single selection.
public final static int SINGLE_INTERVAL_SELECTION
Selection mode: single interval selection.
public final static int MULTIPLE_INTERVAL_SELECTION
Selection mode: multiple interval selection.

3.4.5.4 Constructor

3.4.5.4.1 Introduction

A single constructor is available.

Constructor:

Standard constructor

3.4.5.4.2 Standard constructor

Constructs a JdlSplitList view object with the required resources.

Constructor Definition:
public JdlSplitList(int rows, int cols, String typical, int npart, int[] start_x, String[] titles, boolean hscroll, Insets ins, JdlViewOptions view_opts)
Parameters List:
rows
The required number of character rows (height for list).
cols
The required number of character columns (total width for list).
typical
A typical string for defining column width. If null then the width of the character 'm' is used by default.
npart
The number of vertical columns with movable boundaries (>=1).
start_x
Array of 'npart-1' boundary values (offsets) (minimum separation 10 pixels).
titles
Array of 'npart' titles.
hscroll
If true, display a horizontal scrollbar to enable horizontal scrolling so that long items can be viewed. If false, only display data within the number of columns requested.
ins
Insets around text in list items (If null then values of 1 pixels top/bottom and 4 pixels left/right borders will be selected).
view_opts
Object to set non-default options for borders, active strip, colours and fonts.

3.4.5.5 Operational Methods

3.4.5.5.1 Introduction

This section contains methods to set, get and select list entries.

Methods:

Set strings - setStrings
Notify list reset - notifyListReset
Set titles - setTitles
Select entry - selectItem
Set selection option - setSelectionMode
Get selected entry - getFirstSelectedItem
Get selected entries - getSelectedIndices
Any selected - isSelectionMade
Entry selected - isSelectedIndex
Clear selection - clearSelection

3.4.5.5.2 Set strings - setStrings

This method sets the string entries for the listing.

Method Definition:
public void setStrings (Vector<String[]> strings)
Parameters List:
strings
A vector with one element for each line to be listed. The vector element must be a String array with at least 'npart' (see constructor) elements containing the 'npart' strings to be output for the line. If an additional string (string npart+1) containing the string "Header" is given, then these lines will be treated as section headers; Only the first string will be output as the header (in Italics). If the selection mode is SINGLE_SELECTION and a header line is selected then the action command "Header" will be returned instead of the usual command "Selection made"; otherwise the header line(s) may be included within any multiple line selection.

3.4.5.5.3 Notify list reset - notifyListReset

This method must be called if the string list Vector which has been set via the setStrings(..) method is changed outwith the JdlSplitList object itself e.g. if items have been added or deleted.

Method Definition:
public void notifyListReset()
Parameters List:
none

3.4.5.5.4 Set titles - setTitles

This method sets new title line strings.

Method Definition:
public void setTitles(String[] titles)
Parameters List:
titles
Array of 'npart' titles.

3.4.5.5.5 Select entry - selectItem

This method selects a listed entry.

Method Definition:
public void selectItem(int idx)
Parameters List:
idx
The index (from 0 upwards) of the entry to be selected.

3.4.5.5.6 Set selection option - setSelectionMode

This method sets the list selection option.

Method Definition:
public void setSelectionMode (int mode)
Parameters List:
opt
Selection mode option may be:
SINGLE_SELECTION
SINGLE_INTERVAL_SELECTION
MULTIPLE_INTERVAL_SELECTION

3.4.5.5.7 Get selected entry - getFirstSelectedItem

This method returns the index of the first selected list entry.

Method Definition:
public int getFirstSelectedItem()
Parameters List:
none
Method Return:
The index (-1 if no item or header selected).

3.4.5.5.8 Get selected entries - getSelectedIndices

This method returns a list of indices of the selected list entries. Header entries are omitted from the returned selections.

Method Definition:
public int[] getSelectedIndices ()
Parameters List:
none
Method Return:
Array of the indices (null if no selection).

3.4.5.5.9 Any selected - isSelectionMade

This method tests to see whether or not any list entry is currently selected.

Method Definition:
public boolean isSelectionMade()
Parameters List:
none
Method Return:
True if any entries selected, otherwise false.

3.4.5.5.10 Entry selected - isSelectedIndex

This method tests to see whether a particular list entry has been selected.

Method Definition:
public boolean isSelectedIndex (int idx)
Parameters List:
idx
The index of the list entry to be tested.
Method Return:
True if selected, otherwise false

3.4.5.5.11 Clear selection - clearSelection

This method clears any current selection.

Method Definition:
public void clearSelection()
Parameters List:
none

3.4.5.6 Drag and Drop Methods

3.4.5.6.1 Introduction

This section contains methods to enable drag and drop functions to be used with the JdlSpliList.

Methods:

Set drag option - setDragMode
Set drop mode - setDropMode
Set paste mode - PasteMode

3.4.5.6.2 Set drag option - setDragMode

This method sets the required drag option. Note that no internal drag and drop will take place unless the drop mode set by setDropMode() currently allows a drop to this object.

Method Definition:
public void setDragMode(int mode, boolean active_only)
Parameters List:
mode
The required drag mode
= 0, no drag (the default)
= 1, drag and copy
= 2, drag and move
= 3, drag and copy/move with prompt
active_only
If true and JdlSplitList is being used as a view object (i.e. under the control of the view manager) then only allow drag if the object is 'active' (as indicated by button on active strip) and 'mode>0'. If false the drag depends only on the value of 'mode'.

3.4.5.6.3 Set drop mode - setDropMode

This method sets the required drop option. Note that for the drop to take effect, a strings list Vector must have been defined via the setStrings(..) method though it need not contain any used elements initially.

Method Definition:
public void setDropMode(boolean mode, boolean active_only)
Parameters List:
mode
= true, allow drop; = false, disallow drop (the default)
active_only
If true and JdlSplitList is being used as a view object (i.e. under the control of the view manager) then only allow drop if the object is 'active' (as indicated by button on active strip) and 'mode==true'. If false the drop depends only on the value of 'mode'.

3.4.5.6.4 Set paste mode - PasteMode

This method sets the required paste option. Note that for the paste to take effect, a strings list Vector must have been defined via the setStrings(..) method though it need not contain any used elements initially.

Method Definition:
public void PasteMode(boolean mode, boolean active_only)
Parameters List:
mode
= true, allow paste; = false, disallow paste (the default)
active_only
If true and JdlSplitList is being used as a view object (i.e. under the control of the view manager) then only allow paste if the object is 'active' (as indicated by button on active strip) and 'mode==true'. If false the drop depends only on the value of 'mode'.

3.4.5.7 Standard Positioning and Sizing

3.4.5.7.1 Introduction

This section contains the standard methods for positioning and sizing JdlView objects and getting the current minimum height and width values.

Methods:

Set position constraints - setLocationConstraints
Set size constraints - setSizeConstraints
Set minimum height - setMinimumHeight
Set minimum width - setMinimumWidth

3.4.5.7.2 Set position constraints - setLocationConstraints

Set constraints on the Jdl object positioning.

Method Definition:
public void setLocationConstraints (int constraint_x, int constraint_y)
Parameters List:
constraint_x
Constrain the Jdl Object 'x' position = the required Jdl Object 'x' position (overrides setLocation method) or FREE if the 'x' position may be set by the setLocation method and hence possibly by the layout manager.
constraint_y
Constrain the Jdl Object 'y' position = the required the Jdl Object 'y'position (overrides setLocation method) or FREE if the 'y' position may be set by the setLocation method and hence possibly by the layout manager.

3.4.5.7.3 Set size constraints - setSizeConstraints

Set constraints on the Jdl Object resizing permitted.

Method Definition:
public void setSizeConstraints (int constraint_w, int constraint_h)
Parameters List:
constraint_w
Constrain the Jdl Object width = the required Jdl Object width, or PREFERRED (default) if the width is to be calculated from the current resources, or FREE if the width may be resized to anything greater than the minimum width required.
constraint_h
Constrain the Jdl Object height = the required Jdl Object height, or PREFERRED (default) if the height is to be calculated from the current resources, or FREE if the height may be resized to anything greater than the minimum height required.

3.4.5.7.4 Set minimum height - setMinimumHeight

Set the minimum height resource.

Method Definition:
public void setMinimumHeight(int minh)
Parameters List:
minh
The minimum height required for the object (ignored if less than that required by the minimum layout) (default = 0).

3.4.5.7.5 Set minimum width - setMinimumWidth

Set the minimum width resource.

Method Definition:
public void setMinimumWidth(int minw)
Parameters List:
minh
The minimum width required for the object (ignored if less than that required by the minimum layout) (default = 0).

3.4.5.8 Add/Remove Action Listener

3.4.5.8.1 Introduction

This section has methods to add or remove an action listener.

Methods:

Add action listener - addActionListener
Remove action listener - removeActionListener
Get the returned data - getReturnedData

3.4.5.8.2 Add action listener - addActionListener

This adds the specified action listener to receive action events from this object.

Method Definition:
public void addActionListener(ActionListener listener)
Parameters List:
listener
The action listener to be added.

3.4.5.8.3 Remove action listener - removeActionListener

This removes the specified action listener so that it no longer receives action events from this object.

Method Definition:
public void removeActionListener(ActionListener listener)
Parameters List:
listener
The action listener to be removed.

3.4.5.8.4 Get the returned data - getReturnedData

When run as a view-object, this method enables the last action command to be determined.

Method Definition:
public String getReturnedData()
Parameters List:
none
Method Return:
Returns the last action command.

3.4.5.9 Overriden Superclass Methods

3.4.5.9.1 Introduction

This section contains methods which override the corresponding superclass methods. These are basically standard for JdlView objects and comprise methods to set background and foreground colours and to get the minimum and preferred sizes for the object. (The paintComponent and setSize methods are also over-ridden but they are not normally called by the user).

Methods:

Set background - setBackground
Set background colours - setBackground
Set foreground - setForeground
Get minimum size - getMinimumSize
Get preferred size - getPreferredSize

3.4.5.9.2 Set background - setBackground

This method sets the background colour resource.

Method Definition:
public void setBackground (Color c)
Parameters List:
c
The color to become this object's background color.

3.4.5.9.3 Set background colours - setBackground

This method sets the background colour resource and brighter and darker shades of that colour (e.g. for 3-D frames).

Method Definition:
public void setBackground (Color c, Color brighter, Color darker)
Parameters List:
c
The background colour.
brighter
A brighter shade of the background colour.
darker
A darker shade of the background colour.

3.4.5.9.4 Set foreground - setForeground

This method sets the foreground colour resource.

Method Definition:
public void setForeground (Color c)
Parameters List:
c
The color to become this object's foreground color.

3.4.5.9.5 Get minimum size - getMinimumSize

This method returns the minimum size of the component.

Method Definition:
public Dimension getMinimumSize()
Parameters List:
none

3.4.5.9.6 Get preferred size - getPreferredSize

This method returns the preferred size of the component.

Method Definition:
public Dimension getPreferredSize()
Parameters List:
none

⇑ Up 3   ⇑ Up 2   ⇑ Up 1   ⇑ Top of this