Package org.jcsp.awt

# Class DisplayList

java.lang.Object
org.jcsp.awt.DisplayList

All Implemented Interfaces:
  `Display`, `Paintable`

public class DisplayList extends Object implements Paintable, Display
This implements the `Display` and `Paintable` interfaces and provides a channel-like connection between user processes and an active graphics component.

## Description

A `DisplayList` is a passive object providing graphics services on behalf of a `CSProcess`. It provides an occam3-like `CALL` channel between the application `CSProcess` and the active graphics component (such as ``ActiveCanvas``) on which it wishes to draw.

The user process `set`s, `extend`s or `change`s a list of `GraphicsCommand`s maintained by the `DisplayList`. Any such operation causes the Java Event thread to call back, via the active graphics component, on its `paint` or `update` methods and execute those commands.

The user process sees the ``Display`` interface to the `DisplayList` (in the same way as a writer process sees the `OutputChannel` interface to a `Channel`). The `ActiveCanvas` process sees the ``Paintable`` interface to the `DisplayList` (in the same way as a reader process sees the `InputChannel` interface to a `Channel`).

Unlike a `Channel`, however, a `DisplayList` should never block any of its attached processes indefinitely, regardless of the behaviour of its partner at the other end. The `DisplayList` imposes mutually exclusive access to its state and there are no `wait/notify` operations -- so any delays should be transient. User process sets/extends/changes and `ActiveCanvas` paints/updates on the `DisplayList`, therefore, should always succeed.

Note: the cautionary note in the above paragraph is because Java makes no guarantee that any invocation of a `synchronized` method ever takes place. This is something with which any Java application has to live.

Any number of user processes may draw on the same component via a `DisplayList` -- i.e. it is a any-one channel. By reserving different sections of a `DisplayList` for control by different processes, complex multiple animations can be simply managed.

Note: in this release, only the ``extend`` and ``change`` methods are safe for direct use by multiple user processes on the same `DisplayList`. A process should only invoke ``set`` at times when it knows others cannot be operating on that `DisplayList`. This would normally be required by an application, since a `DisplayList` re `set` invalidates the result returned by a previous `extend` and the base index used in a `change` -- i.e. concurrent processes doing these things will need to be informed before they do them again! However, if the list really needs concurrent setting without such an arrangement, this can be done within a `synchronized` block on the `DisplayList`.

User applications will not normally be implementing new processes that are at the receiving end of a `DisplayList`. Users will only be responsible for connecting a `DisplayList` to a standard `org.jcsp.awt` drawing component. This can either be done statically (e.g. through ``setPaintable``) or dynamically (by sending a `GraphicsProtocol.SetPaintable` object through a `GraphicsProtocol` channel).

Author:
  P.H. Welch
See Also:
  - `GraphicsCommand`
  - `Display`
  - `Paintable`
  - `ActiveCanvas`

## Constructor Summary

Constructors
Constructor
Description
`DisplayList()`

## Method Summary

Modifier and Type
Method
Description
`boolean`
`change(GraphicsCommand[] c, int i)`
Changes the array of `GraphicsCommand`s to be executed by replacing elements `i` onwards with the new ones.
`boolean`
`change(GraphicsCommand c, int i)`
Changes the array of `GraphicsCommand`s to be executed by replacing element `i` with the new one.
`int`
`extend(GraphicsCommand c)`
Extends the array of `GraphicsCommand`s to be executed by one command.
`int`
`extend(GraphicsCommand[] c)`
Extends the array of `GraphicsCommand`s to be executed.
`GraphicsCommand[]`
`get()`
Returns a copy of the array of `GraphicsCommand`s currently held.
`void`
`paint(Graphics g)`
This is the call-back delegated here by the registered `Component`.
`void`
`register(Component c)`
Register the `Component` that will delegate its `paint` and `update` methods here.
`void`
`set(GraphicsCommand c)`
Sets the `GraphicsCommand` to be executed.
`void`
`set(GraphicsCommand[] c)`
Sets the array of `GraphicsCommand`s to be executed.
`void`
`setMinRefreshInterval(long minRefreshInterval)`
Sets the `repaint` interval invoked by the ``set``, ``extend`` and ``change`` commands.
`void`
`update(Graphics g)`
This is the call-back delegated here by the registered `Component`.

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

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

## Constructor Details

### DisplayList

public DisplayList()

## Method Details

### set

public void set(GraphicsCommand[] c)
Sets the array of `GraphicsCommand`s to be executed. The commands will be executed in ascending order of index. The `repaint` method of the registered component is called to trigger the ``update`` callback on this object. All commands will be executed.

Specified by:
  `set` in interface `Display`
Parameters:
  `c` - the array of GraphicsCommands to be executed.

### set

public void set(GraphicsCommand c)
Sets the `GraphicsCommand` to be executed. The `repaint` method of the registered component is called to trigger the ``update`` callback on this object.

Specified by:
  `set` in interface `Display`
Parameters:
  `c` - the GraphicsCommand to be executed.

### extend

public int extend(GraphicsCommand[] c)
Extends the array of `GraphicsCommand`s to be executed. The `repaint` method of the registered component is called to trigger the ``update`` callback on this object. Only the new commands will be executed.

Specified by:
  `extend` in interface `Display`
Parameters:
  `c` - the extra GraphicsCommands to be executed.
Returns:
  the start index of the extension.

### extend

public int extend(GraphicsCommand c)
Extends the array of `GraphicsCommand`s to be executed by one command. The `repaint` method of the registered component is called to trigger the ``update`` callback on this object. Only the new command will be executed.

Specified by:
  `extend` in interface `Display`
Parameters:
  `c` - the extra GraphicsCommand to be executed.
Returns:
  the start index of the extension.

### change

public boolean change(GraphicsCommand[] c, int i)
Changes the array of `GraphicsCommand`s to be executed by replacing elements `i` onwards with the new ones. There must be at least `(i + c.length)` elements in the original array -- else this method will not change anything and will return false. The `repaint` method of the registered component is called to trigger the ``update`` callback on this object. All commands will be executed.

Specified by:
  `change` in interface `Display`
Parameters:
  `c` - the new GraphicsCommands to be executed.
  `i` - the start index for the replacement.
Returns:
  true if and only if the changes are successfully made.

### change

public boolean change(GraphicsCommand c, int i)
Changes the array of `GraphicsCommand`s to be executed by replacing element `i` with the new one. There must be at least `(i + 1)` elements in the original array -- else this method will not change anything and will return false. The `repaint` method of the registered component is called to trigger the ``update`` callback on this object. All commands will be executed.

Specified by:
  `change` in interface `Display`
Parameters:
  `c` - the new GraphicsCommand to be executed.
  `i` - the index for the replacement.
Returns:
  true if and only if the change is successfully made.

### get

public GraphicsCommand[] get()
Returns a copy of the array of `GraphicsCommand`s currently held.

Specified by:
  `get` in interface `Display`
Returns:
  a copy of the array of `GraphicsCommand`s currently held.

### setMinRefreshInterval

public void setMinRefreshInterval(long minRefreshInterval)
Sets the `repaint` interval invoked by the ``set``, ``extend`` and ``change`` commands. The default is 10 milliseconds (the normal default for the ``repaint`` method from `Component`).

Parameters:
  `minRefreshInterval` - the display commands will be executed at most once per `minRefreshInterval` milliseconds.

### register

public void register(Component c)
Register the `Component` that will delegate its `paint` and `update` methods here. Only the JCSP `Active` component should perform this registration (in response to being passed this `Paintable`).

Specified by:
  `register` in interface `Paintable`
Parameters:
  `c` - the Component that will do the delegating.

### paint

public void paint(Graphics g)
This is the call-back delegated here by the registered `Component`. It will normally be the JVM event thread that is making this call.

Specified by:
  `paint` in interface `Paintable`
Parameters:
  `g` - the graphics context for the painting.

### update

public void update(Graphics g)
This is the call-back delegated here by the registered `Component`. It will normally be the JVM event thread that is making this call.

Specified by:
  `update` in interface `Paintable`
Parameters:
  `g` - the graphics context for the painting.