Package org.jcsp.awt

# Class ActiveCheckboxMenuItem

java.lang.Object
java.awt.MenuComponent
java.awt.MenuItem
java.awt.CheckboxMenuItem
org.jcsp.awt.ActiveCheckboxMenuItem

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

public class ActiveCheckboxMenuItem extends CheckboxMenuItem implements CSProcess
``java.awt.CheckboxMenuItem`` with a channel interface.

## Process Diagram

## Description

`ActiveCheckboxMenuItem` is a process extension of `java.awt.CheckboxMenuItem` 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. The `event` channel delivers the generated `java.awt.ItemEvent` whenever the `ActiveCheckboxMenuItem` is selected. 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 myCheckboxMenuItemEvent = Channel.one2one (new OverWriteOldestBuffer (n));

       final ActiveCheckboxMenuItem myCheckboxMenuItem =
         new ActiveCheckboxMenuItem (null, myCheckboxMenuItemEvent.out (), "Choose Me");

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 | Change the label on the `ActiveCheckboxMenuItem` to the value of the `String`
java.awt.MenuShortcut | Sets the `MenuShortcut` for the `ActiveCheckboxMenuItem`

Boolean

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

ActiveCheckboxMenuItem.Configure | Invoke the user-defined `Configure.configure` method on the checkboxMenuItem.
Output Channels
event | java.awt.ItemEvent | The generated `java.awt.ItemEvent` is written down this channel (when the checkboxMenuItem is selected or deslected)
actionEvent | ActionEvent | See the ``addActionEventChannel`` method.

## Example

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

     public class ActiveCheckboxMenuItemExample {

       public static void main (String argv[]) {

         final ActiveClosingFrame activeClosingFrame =
           new ActiveClosingFrame ("ActiveCheckboxMenuItem Example");

         final ActiveFrame frame = activeClosingFrame.getActiveFrame ();

         final MenuBar menuBar = new MenuBar ();
         frame.setMenuBar (menuBar);

         final Menu fileMenu = new Menu ("File");
         final Menu langMenu = new Menu ("Language");
         menuBar.add (fileMenu);
         menuBar.add (langMenu);

         final String[] fileOptions = {"Hello World", "Rocket Science", "CSP",
                                       "Monitors", "Ignore Me", "Goodbye World"};
         final String[] langOptions = {"occam-pi", "Java", "Smalltalk", "Algol-60",
                                       "Pascal", "Haskell", "SML", "Lisp"};

         final Any2OneChannel event[] = Channel.any2oneArray (2, new OverWriteOldestBuffer (10));

         final ActiveMenuItem[] fileMenuItem =
           new ActiveMenuItem[fileOptions.length];
         for (int i = 0; i invalid input: '<' fileOptions.length; i++) {
           fileMenuItem[i] = new ActiveMenuItem (null, event[0].out (), fileOptions[i]);
           fileMenu.add (fileMenuItem[i]);
         }

         final ActiveCheckboxMenuItem[] langCheckboxMenuItem =
           new ActiveCheckboxMenuItem[langOptions.length];
         for (int i = 0; i invalid input: '<' langOptions.length; i++) {
           langCheckboxMenuItem[i] =
             new ActiveCheckboxMenuItem (null, event[1].out (), langOptions[i]);
           langMenu.add (langCheckboxMenuItem[i]);
         }

         frame.setSize (300, 200);
         frame.setBackground (Color.green);
         frame.setVisible (true);

         new Parallel (
           new CSProcess[] {
             activeClosingFrame,
             new Parallel (fileMenuItem),
             new Parallel (langCheckboxMenuItem),
             new CSProcess () {
               public void run () {
                 boolean running = true;
                 while (running) {
                   final String s = (String) event[0].in ().read ();
                   System.out.println ("File ==> `" + s + "' selected ...");
                   running = (s != fileOptions[fileOptions.length - 1]);
                 }
                 frame.setVisible (false);
                 System.exit (0);
               }
             },
             new CSProcess () {
               public void run () {
                 while (true) {
                   final ItemEvent e = (ItemEvent) event[1].in ().read ();
                   final String item = (String) e.getItem ();
                   System.out.print ("Language ==> `" + item);
                   if (e.getStateChange () == ItemEvent.SELECTED) {
                     System.out.println ("' selected ...");
                   } else {
                     System.out.println ("' deselected ...");
                   }
                 }
               }
             }
           }
         ).run ();

       }

     }

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

## Nested Class Summary

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

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

`CheckboxMenuItem.AccessibleAWTCheckboxMenuItem`

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

`MenuItem.AccessibleAWTMenuItem`

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

`MenuComponent.AccessibleAWTMenuComponent`

## Constructor Summary

Constructors
Constructor
Description
`ActiveCheckboxMenuItem()`
Constructs a new unchecked `ActiveCheckboxMenuItem` with no initial label and no configuration or event channels.
`ActiveCheckboxMenuItem(String s)`
Constructs a new unchecked `ActiveCheckboxMenuItem` with no configuration or event channels.
`ActiveCheckboxMenuItem(String s, boolean state)`
Constructs a new `ActiveCheckboxMenuItem` with no configuration or event channels.
`ActiveCheckboxMenuItem(ChannelInput configure, ChannelOutput event)`
Constructs a new unchecked `ActiveCheckboxMenuItem` with no initial label.
`ActiveCheckboxMenuItem(ChannelInput configure, ChannelOutput event, String s)`
Constructs a new unchecked `ActiveCheckboxMenuItem`.
`ActiveCheckboxMenuItem(ChannelInput configure, ChannelOutput event, String s, boolean state)`
Constructs a new `ActiveCheckboxMenuItem`.

## Method Summary

Modifier and Type
Method
Description
`void`
`addActionEventChannel(ChannelOutput actionEvent)`
Add a new channel to this component that will be used to notify that an `ActionEvent` has occurred.
`void`
`run()`
The main body of this process.
`void`
`setConfigureChannel(ChannelInput configure)`
Sets the configuration channel for this `ActiveCheckboxMenuItem`.

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

`addItemListener, addNotify, getAccessibleContext, getItemListeners, getListeners, getSelectedObjects, getState, paramString, processEvent, processItemEvent, removeItemListener, setState`

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

`addActionListener, deleteShortcut, disable, disableEvents, enable, enable, enableEvents, getActionCommand, getActionListeners, getLabel, getShortcut, isEnabled, processActionEvent, removeActionListener, setActionCommand, setEnabled, setLabel, setShortcut`

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

`dispatchEvent, getFont, getName, getParent, getTreeLock, postEvent, removeNotify, setFont, setName, toString`

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

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

## Constructor Details

### ActiveCheckboxMenuItem

public ActiveCheckboxMenuItem()
Constructs a new unchecked `ActiveCheckboxMenuItem` with no initial label and no configuration or event channels.

### ActiveCheckboxMenuItem

public ActiveCheckboxMenuItem(String s)
Constructs a new unchecked `ActiveCheckboxMenuItem` with no configuration or event channels.

Parameters:
  `s` - the initial label displayed on the checkboxMenuItem.

### ActiveCheckboxMenuItem

public ActiveCheckboxMenuItem(String s, boolean state)
Constructs a new `ActiveCheckboxMenuItem` with no configuration or event channels.

Parameters:
  `s` - the initial label displayed on the checkboxMenuItem.
  `state` - the initial state of the checkboxMenuItem.

### ActiveCheckboxMenuItem

public ActiveCheckboxMenuItem(ChannelInput configure, ChannelOutput event)
Constructs a new unchecked `ActiveCheckboxMenuItem` with no initial label.

Parameters:
  `configure` - the channel for configuration events -- can be null if no configuration is required.
  `event` - the current label will be output when the checkboxMenuItem is selected -- can be null if no notification is required.

### ActiveCheckboxMenuItem

public ActiveCheckboxMenuItem(ChannelInput configure, ChannelOutput event, String s)
Constructs a new unchecked `ActiveCheckboxMenuItem`.

Parameters:
  `configure` - the channel for configuration events -- can be null if no configuration is required.
  `event` - the current label will be output when the checkboxMenuItem is selected -- can be null if no notification is required.
  `s` - the initial label displayed on the checkboxMenuItem.

### ActiveCheckboxMenuItem

public ActiveCheckboxMenuItem(ChannelInput configure, ChannelOutput event, String s, boolean state)
Constructs a new `ActiveCheckboxMenuItem`.

Parameters:
  `configure` - the channel for configuration events -- can be null if no configuration is required.
  `event` - the current label will be output when the checkboxMenuItem is selected -- can be null if no notification is required.
  `s` - the initial label displayed on the checkboxMenuItem.
  `state` - the initial state of the checkboxMenuItem.

## Method Details

### setConfigureChannel

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

### addActionEventChannel

public void addActionEventChannel(ChannelOutput actionEvent)
Add a new channel to this component that will be used to notify that an `ActionEvent` has occurred. This should be used instead of registering a ActionListener 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:
  `actionEvent` - the channel down which to send ActionEvents.

### run

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

Specified by:
  `run` in interface `CSProcess`