Package org.jcsp.awt

# Class ActiveClosingFrame

java.lang.Object
org.jcsp.awt.ActiveClosingFrame

All Implemented Interfaces:
  `CSProcess`

public class ActiveClosingFrame extends Object implements CSProcess
A specialisation of `ActiveFrame` that forces a `System.exit` upon a Window Closing event.

## Process Diagram

## Description

`ActiveClosingFrame` is a process containing an ``ActiveFrame``, configured with channels for event notification and configuration. 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.

The difference between this class and `ActiveFrame` is that a Window Closing event, generated on the (internal) `ActiveFrame`, is intercepted by the anonymous process and results in a `System.exit`. This happens regardless as to whether the (external) `event` channel is null. Otherwise, `WindowEvent`s are forwarded to the (external) `event` channel, so long as it's not null).

The internal `ActiveFrame` can be extracted with the `getActiveFrame` method. Channels can then be added to notify the occurrence of any other type of `Event` the `ActiveFrame` generates. This is done by calling its appropriate `add` XXX `EventChannel` method (before the process is run). As many channels can be added as are needed.

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 the output channels from this process are always serviced -- otherwise the Java Event Thread will be blocked and the GUI will stop responding. The simplest way to guarantee this is to use channels configured with overwriting buffers. For example:

       final One2OneChannel myWindowEvent = Channel.one2one (new OverWriteOldestBuffer (n));
       final One2OneChannel myMouseEvent = Channel.one2one (new OverWriteOldestBuffer (n));

       final ActiveClosingFrame myFrame = new ActiveClosingFrame (myWindowEvent.out ());
       final ActiveFrame myActiveFrame = myFrame.getActiveFrame ();
       myActiveFrame.addMouseEventChannel (myMouseEvent.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

Boolean

1. If this is the `Boolean.TRUE` object, the frame is made visible
2. If this is the `Boolean.FALSE` object, the frame is made invisible
3. Other `Boolean` objects are ignored

ActiveFrame.Configure | Invoke the user-defined `Configure.configure` method on the frame.
Output Channels
event | WindowEvent | The `WindowEvent` generated by the component (note that Window Closing is handled locally to cause a `System.exit`).
containerEvent | ContainerEvent | See the ``getActiveFrame``.``addContainerEventChannel`` method.
componentEvent | ComponentEvent | See the ``getActiveFrame``.``addComponentEventChannel`` method.
focusEvent | FocusEvent | See the ``getActiveFrame``.``addFocusEventChannel`` method.
keyEvent | KeyEvent | See the ``getActiveFrame``.``addKeyEventChannel`` method.
mouseEvent | MouseEvent | See the ``getActiveFrame``.``addMouseEventChannel`` method.
mouseMotionEvent | MouseEvent | See the ``getActiveFrame``.``addMouseMotionEventChannel`` method.

## Example

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

     public class ActiveClosingFrameButtonExample {

       public static void main (String argv[]) {

         final ActiveClosingFrame frame =
           new ActiveClosingFrame ("ActiveClosingFrameButton Example");

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

         final Any2OneChannel buttonEvent = Channel.any2one (new OverWriteOldestBuffer (10));

         final ActiveButton[] button = new ActiveButton[label.length];
         for (int i = 0; i invalid input: '<' label.length; i++) {
           button[i] = new ActiveButton (null, buttonEvent.out (), label[i]);
         }

         final Frame realFrame = frame.getActiveFrame ();
         realFrame.setSize (300, 200);
         realFrame.setLayout (new GridLayout (label.length/2, 2));
         for (int i = 0; i invalid input: '<' label.length; i++) {
           realFrame.add (button[i]);
         }
         realFrame.setVisible (true);

         new Parallel (
           new CSProcess[] {
             frame,
             new Parallel (button),
             new CSProcess () {
               public void run () {
                 boolean running = true;
                 while (running) {
                   final String s = (String) buttonEvent.in ().read ();
                   System.out.println ("Button `" + s + "' pressed ...");
                   running = (s != label[label.length - 1]);
                 }
                 realFrame.setVisible (false);
                 System.exit (0);
               }
             }
           }
         ).run ();

       }

     }

Author:
  P.D. Austin and P.H. Welch
See Also:
  - `ActiveFrame`
  - `Frame`
  - `ContainerEvent`
  - `ComponentEvent`
  - `FocusEvent`
  - `KeyEvent`
  - `MouseEvent`
  - `OverWriteOldestBuffer`

## Constructor Summary

Constructors
Constructor
Description
`ActiveClosingFrame()`
Constructs a new `ActiveClosingFrame` with no title and no configuration or event channels.
`ActiveClosingFrame(String title)`
Constructs a new `ActiveClosingFrame` with a title but no configuration or event channels.
`ActiveClosingFrame(ChannelInput configure, ChannelOutput event)`
Constructs a new `ActiveClosingFrame` with configuration and event channels, but no title.
`ActiveClosingFrame(ChannelInput configure, ChannelOutput event, String title)`
Constructs a new `ActiveClosingFrame` with configuration and event channels and a title.

## Method Summary

Modifier and Type
Method
Description
`ActiveFrame`
`getActiveFrame()`
This is used to get the `ActiveFrame` within this component so that it can be configured or have components added (using `Frame` or `ActiveFrame` methods).
`void`
`run()`
The main body of this process.
`void`
`setConfigureChannel(ChannelInput configure)`
Sets the configuration channel for this `ActiveButton`.

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

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

## Constructor Details

### ActiveClosingFrame

public ActiveClosingFrame()
Constructs a new `ActiveClosingFrame` with no title and no configuration or event channels.

### ActiveClosingFrame

public ActiveClosingFrame(String title)
Constructs a new `ActiveClosingFrame` with a title but no configuration or event channels.

Parameters:
  `title` - the title for the frame.

### ActiveClosingFrame

public ActiveClosingFrame(ChannelInput configure, ChannelOutput event)
Constructs a new `ActiveClosingFrame` with configuration and event channels, but no title.

Parameters:
  `configure` - the channel for configuration events -- can be null if no configuration is required.
  `event` - a WindowEvent will be output whenever it occurs -- can be null if no notification is required.

### ActiveClosingFrame

public ActiveClosingFrame(ChannelInput configure, ChannelOutput event, String title)
Constructs a new `ActiveClosingFrame` with configuration and event channels and a title.

Parameters:
  `configure` - the channel for configuration events -- can be null if no configuration is required.
  `event` - a WindowEvent will be output whenever it occurs -- can be null if no notification is required.
  `title` - the title for the frame.

## Method Details

### setConfigureChannel

public void setConfigureChannel(ChannelInput configure)
Sets the configuration channel for this `ActiveButton`. 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.

### getActiveFrame

public ActiveFrame getActiveFrame()
This is used to get the `ActiveFrame` within this component so that it can be configured or have components added (using `Frame` or `ActiveFrame` methods). For example, event channels can be added by invoking `getActiveFrame().add` XXX `EventChannel(...)`.

NOTE: This must be finished before this process is run.

Returns:
  the `Frame` within this component.

### run

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

Specified by:
  `run` in interface `CSProcess`