Package org.jcsp.awt

# Class ActiveList

java.lang.Object
java.awt.Component
java.awt.List
org.jcsp.awt.ActiveList

All Implemented Interfaces:
  `ImageObserver`, `ItemSelectable`, `MenuContainer`, `Serializable`, `Accessible`, `CSProcess`

public class ActiveList extends List implements CSProcess
``java.awt.List`` with a channel interface.

## Process Diagram

## Description

`ActiveList` is a process extension of `java.awt.List` with channels for run-time configuration and event notification. The event channels should be connected to one or more application-specific server processes (instead of registering a passive object as a Listener to this component).

All channels are optional. The `configure` and `event` channels are settable from a constructor. When an item in the `ActiveList` is double-clicked, its label is written down the `event` channel. Other event channels can be added to notify the occurrence of any other events the component generates (by calling the appropriate `add` XXX `EventChannel` method before the process is run). Messages can be sent down the `configure` channel at any time to configure the component. See the table below for details.

All channels are managed by independent internal handler processes. It is, therefore, safe for a serial application process both to service an event channel and configure the component -- no deadlock can occur.

IMPORTANT: it is essential that event channels from this process are always serviced -- otherwise the Java Event Thread will be blocked and the GUI will stop responding. A simple way to guarantee this is to use channels configured with overwriting buffers. For example:

       final One2OneChannel myListEvent = Channel.one2one (new OverWriteOldestBuffer (n));
       final One2OneChannel myListItemEvent = Channel.one2one (new OverWriteOldestBuffer (n));

       final ActiveList myList = new ActiveList (null, myListEvent.out ());
       myList.addItemEventChannel (myListItemEvent.out ());

This will ensure that the Java Event Thread will never be blocked. Slow or inattentive readers may miss rapidly generated events, but the `n` most recent events will always be available.

## Channel Protocols

Input Channels
configure | String | Empty strings are ignored. If the string is `"-*"`, all items in the list are removed. Otherwise, if the first character is `'-'`, the item corresponding to the tail of the string is removed from the list. Otherwise, the string is added to the end of the list.
Integer | Sets the selected item in this `ActiveList` list to be the item at the specified position.

Boolean

1. If this is the `Boolean.TRUE` object, the list is made active
2. If this is the `Boolean.FALSE` object, the list is made inactive
3. Other `Boolean` objects are ignored

ActiveList.Configure | Invoke the user-defined `Configure.configure` method on the list.
Output Channels
event | String | When an item in the `ActiveList` is double-clicked, its label is written down this channel.
itemEvent | ItemEvent | See the ``addItemEventChannel`` method.
componentEvent | ComponentEvent | See the ``addComponentEventChannel`` method.
focusEvent | FocusEvent | See the ``addFocusEventChannel`` method.
keyEvent | KeyEvent | See the ``addKeyEventChannel`` method.
mouseEvent | MouseEvent | See the ``addMouseEventChannel`` method.
mouseMotionEvent | MouseEvent | See the ``addMouseMotionEventChannel`` method.

## Example

     import java.awt.*;
     import java.awt.event.*;
     import org.jcsp.lang.*;
     import org.jcsp.util.*;
     import org.jcsp.awt.*;

     public class ActiveListExample {

       public static void main (String argv[]) {

         final Frame root = new Frame ("ActiveList Example");

         final One2OneChannel configure = Channel.one2one ();

         final One2OneChannel event = Channel.one2one (new OverWriteOldestBuffer (10));
         final One2OneChannel itemEvent = Channel.one2one (new OverWriteOldestBuffer (10));

         final ActiveList list = new ActiveList (configure.in (), event.out (), 0, true);
         list.addItemEventChannel (itemEvent.out ());

         final String[] menu = {"Hello World", "Rocket Science", "CSP",
                               "Monitors", "Ignore Me", "Goodbye World"};

         for (int i = 0; i invalid input: '<' menu.length; i++) {
           list.add (menu[i]);
         }

         root.setSize (300, 105);
         root.add (list);
         root.setVisible (true);

         new Parallel (
           new CSProcess[] {           // respond to the event channel
             list,
             new CSProcess () {
               public void run () {
                 boolean running = true;
                 while (running) {
                   final String s = (String) event.in ().read ();
                   System.out.println ("                         Action ==> `" + s + "'");
                   running = (s != menu[menu.length - 1]);
                 }
                 root.setVisible (false);
                 System.exit (0);
               }
             },
             new CSProcess () {        // respond to the itemEvent channel
               public void run () {
                 while (true) {
                   final ItemEvent e = (ItemEvent) itemEvent.in ().read ();
                   final Integer item = (Integer) e.getItem ();
                   if (e.getStateChange () == ItemEvent.SELECTED) {
                     System.out.println ("Selected item " + item);
                   } else {
                     System.out.println ("Unselected item " + item);
                   }
                 }
               }
             },
             new CSProcess () {        // dynamically reconfigure the list
               public void run () {
                 CSTimer tim = new CSTimer ();
                 long timeout = tim.read ();
                 while (true) {
                   timeout += 10000;
                   tim.after (timeout);
                   System.out.println ("*** Removing last three items ...");
                   for (int i = 3; i invalid input: '<' menu.length; i++) {
                     configure.out ().write ("-" + menu[i]);
                   }
                   timeout += 10000;
                   tim.after (timeout);
                   System.out.println ("*** Restoring last three items ...");
                   for (int i = 3; i invalid input: '<' menu.length; i++) {
                     configure.out ().write (menu[i]);
                   }
                 }
               }
             }
           }
         ).run ();

       }

     }

Author:
  P.D. Austin and P.H. Welch
See Also:
  - `List`
  - `ItemEvent`
  - `ComponentEvent`
  - `FocusEvent`
  - `KeyEvent`
  - `MouseEvent`
  - `OverWriteOldestBuffer`
  - Serialized Form

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static interface`
`ActiveList.Configure`
This enables general configuration of this component.

## Nested classes/interfaces inherited from class java.awt.List

`List.AccessibleAWTList`

## Nested classes/interfaces inherited from class java.awt.Component

`Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy`

## Field Summary

### Fields inherited from class java.awt.Component

`accessibleContext, BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT`

### Fields inherited from interface java.awt.image.ImageObserver

`ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH`

## Constructor Summary

Constructors
Constructor
Description
`ActiveList()`
Constructs an `ActiveList` with no visible lines, no configuration or event channels and only one item selectable.
`ActiveList(int rows)`
Constructs an `ActiveList` with the specified number of visible lines, but with no configuration or event channels and only one item selectable.
`ActiveList(int rows, boolean multipleMode)`
Constructs an `ActiveList` with the specified number of visible lines and a multiple selection option, but with no configuration or event channels.
`ActiveList(ChannelInput configure, ChannelOutput event)`
Constructs an `ActiveList` with configuration and event channels, but no visible items and only one item selectable.
`ActiveList(ChannelInput configure, ChannelOutput event, int rows)`
Constructs an `ActiveList` with configuration and event channels, the specified number of visible lines and only one item selectable.
`ActiveList(ChannelInput configure, ChannelOutput event, int rows, boolean multipleMode)`
Constructs an `ActiveList` with configuration and event channels, the specified number of visible lines and a multiple selection option.

## Method Summary

Modifier and Type
Method
Description
`void`
`addComponentEventChannel(ChannelOutput componentEvent)`
Add a new channel to this component that will be used to notify that a `ComponentEvent` has occurred.
`void`
`addFocusEventChannel(ChannelOutput focusEvent)`
Add a new channel to this component that will be used to notify that a `FocusEvent` has occurred.
`void`
`addItemEventChannel(ChannelOutput itemEvent)`
Add a new channel to this component that will be used to notify that an `ItemEvent` has occurred.
`void`
`addKeyEventChannel(ChannelOutput keyEvent)`
Add a new channel to this component that will be used to notify that a `KeyEvent` has occurred.
`void`
`addMouseEventChannel(ChannelOutput mouseEvent)`
Add a new channel to this component that will be used to notify that a `MouseEvent` has occurred.
`void`
`addMouseMotionEventChannel(ChannelOutput mouseMotionEvent)`
Add a new channel to this component that will be used to notify that a `MouseMotionEvent` has occurred.
`void`
`run()`
The main body of this process.
`void`
`setConfigureChannel(ChannelInput configure)`
Sets the configuration channel for this `ActiveList`.

### Methods inherited from class java.awt.List

`add, add, addActionListener, addItem, addItem, addItemListener, addNotify, allowsMultipleSelections, clear, countItems, delItem, delItems, deselect, getAccessibleContext, getActionListeners, getItem, getItemCount, getItemListeners, getItems, getListeners, getMinimumSize, getMinimumSize, getPreferredSize, getPreferredSize, getRows, getSelectedIndex, getSelectedIndexes, getSelectedItem, getSelectedItems, getSelectedObjects, getVisibleIndex, isIndexSelected, isMultipleMode, isSelected, makeVisible, minimumSize, minimumSize, paramString, preferredSize, preferredSize, processActionEvent, processEvent, processItemEvent, remove, remove, removeActionListener, removeAll, removeItemListener, removeNotify, replaceItem, select, setMultipleMode, setMultipleSelections`

### Methods inherited from class java.awt.Component

`action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, deliverEvent, disable, disableEvents, dispatchEvent, doLayout, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getAlignmentX, getAlignmentY, getBackground, getBaseline, getBaselineResizeBehavior, getBounds, getBounds, getColorModel, getComponentAt, getComponentAt, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeys, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMaximumSize, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, invalidate, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusCycleRoot, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, layout, list, list, list, list, list, locate, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paint, paintAll, postEvent, prepareImage, prepareImage, print, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, requestFocusInWindow, reshape, resize, resize, revalidate, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeys, setFocusTraversalKeysEnabled, setFont, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setMixingCutoutShape, setName, setPreferredSize, setSize, setSize, setVisible, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle, update, validate`

### Methods inherited from class java.lang.Object

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

## Constructor Details

### ActiveList

public ActiveList()
Constructs an `ActiveList` with no visible lines, no configuration or event channels and only one item selectable.

### ActiveList

public ActiveList(int rows)
Constructs an `ActiveList` with the specified number of visible lines, but with no configuration or event channels and only one item selectable.

Parameters:
  `rows` - the number of visible lines.

### ActiveList

public ActiveList(int rows, boolean multipleMode)
Constructs an `ActiveList` with the specified number of visible lines and a multiple selection option, but with no configuration or event channels.

Parameters:
  `rows` - the number of visible lines.
  `multipleMode` - the multiple selection option.

### ActiveList

public ActiveList(ChannelInput configure, ChannelOutput event)
Constructs an `ActiveList` with configuration and event channels, but no visible items and only one item selectable.

Parameters:
  `configure` - the channel for configuration events -- can be null if no configuration is required.
  `event` - the String label from a list item will be output when it is double-clicked -- can be null if no notification is required.

### ActiveList

public ActiveList(ChannelInput configure, ChannelOutput event, int rows)
Constructs an `ActiveList` with configuration and event channels, the specified number of visible lines and only one item selectable.

Parameters:
  `configure` - the channel for configuration events -- can be null if no configuration is required.
  `event` - the String label from a list item will be output when it is double-clicked -- can be null if no notification is required.
  `rows` - the number of visible lines.

### ActiveList

public ActiveList(ChannelInput configure, ChannelOutput event, int rows, boolean multipleMode)
Constructs an `ActiveList` with configuration and event channels, the specified number of visible lines and a multiple selection option.

Parameters:
  `configure` - the channel for configuration events -- can be null if no configuration is required.
  `event` - the String label from a list item will be output when it is double-clicked -- can be null if no notification is required.
  `rows` - the number of visible lines.
  `multipleMode` - the multiple selection option.

## Method Details

### setConfigureChannel

public void setConfigureChannel(ChannelInput configure)
Sets the configuration channel for this `ActiveList`. This method overwrites any configuration channel set in the constructor.

Parameters:
  `configure` - the channel for configuration events -- can be null if no configuration is required.

### addItemEventChannel

public void addItemEventChannel(ChannelOutput itemEvent)
Add a new channel to this component that will be used to notify that an `ItemEvent` has occurred. This should be used instead of registering a ItemListener with the component. It is possible to add more than one channel by calling this method multiple times If the channel passed is `null`, no action will be taken.

NOTE: This method must be called before this process is run.

Parameters:
  `itemEvent` - the channel down which to send ItemEvents.

### addComponentEventChannel

public void addComponentEventChannel(ChannelOutput componentEvent)
Add a new channel to this component that will be used to notify that a `ComponentEvent` has occurred. This should be used instead of registering a ComponentListener with the component. It is possible to add more than one channel by calling this method multiple times If the channel passed is `null`, no action will be taken.

NOTE: This method must be called before this process is run.

Parameters:
  `componentEvent` - the channel down which to send ComponentEvents.

### addFocusEventChannel

public void addFocusEventChannel(ChannelOutput focusEvent)
Add a new channel to this component that will be used to notify that a `FocusEvent` has occurred. This should be used instead of registering a FocusListener with the component. It is possible to add more than one channel by calling this method multiple times If the channel passed is `null`, no action will be taken.

NOTE: This method must be called before this process is run.

Parameters:
  `focusEvent` - the channel down which to send FocusEvents.

### addKeyEventChannel

public void addKeyEventChannel(ChannelOutput keyEvent)
Add a new channel to this component that will be used to notify that a `KeyEvent` has occurred. This should be used instead of registering a KeyListener with the component. It is possible to add more than one channel by calling this method multiple times If the channel passed is `null`, no action will be taken.

NOTE: This method must be called before this process is run.

Parameters:
  `keyEvent` - the channel down which to send KeyEvents.

### addMouseEventChannel

public void addMouseEventChannel(ChannelOutput mouseEvent)
Add a new channel to this component that will be used to notify that a `MouseEvent` has occurred. This should be used instead of registering a MouseListener with the component. It is possible to add more than one channel by calling this method multiple times If the channel passed is `null`, no action will be taken.

NOTE: This method must be called before this process is run.

Parameters:
  `mouseEvent` - the channel down which to send MouseEvents.

### addMouseMotionEventChannel

public void addMouseMotionEventChannel(ChannelOutput mouseMotionEvent)
Add a new channel to this component that will be used to notify that a `MouseMotionEvent` has occurred. This should be used instead of registering a MouseMotionListener with the component. It is possible to add more than one channel by calling this method multiple times If the channel passed is `null`, no action will be taken.

NOTE: This method must be called before this process is run.

Parameters:
  `mouseMotionEvent` - the channel down which to send MouseMotionEvents.

### run

public void run()
The main body of this process.

Specified by:
  `run` in interface `CSProcess`