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 sets, extends or changes a list of GraphicsCommands 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 reset 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).

See Also:

  • Field Details

    • component

      private Component component

    • size

      private Dimension size

    • image

      private Image image

    • imageGraphics

      private Graphics imageGraphics

    • INITIAL_MAX_COMMANDS

      private final int INITIAL_MAX_COMMANDS
      See Also:

    • command

      private GraphicsCommand[] command

    • maxCommands

      private int maxCommands

    • nCommands

      private int nCommands

    • updateIndex

      private int updateIndex

    • refresh

      private boolean refresh

    • updated

      private boolean updated

    • minRefreshInterval

      private long minRefreshInterval

  • Constructor Details

    • DisplayList

      public DisplayList()

  • Method Details

    • set

      public void set(GraphicsCommand[] c)
      Sets the array of GraphicsCommands 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 GraphicsCommands 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 GraphicsCommands 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 GraphicsCommands 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 GraphicsCommands 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 GraphicsCommands currently held.

      Specified by:
      get in interface Display
      Returns:
      a copy of the array of GraphicsCommands 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.

    • execute

      private void execute(int start, Graphics g)

    • 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.