Package org.jcsp.awt

# Class ActiveTextEnterField

java.lang.Object
org.jcsp.awt.ActiveTextEnterField

All Implemented Interfaces:
  `CSProcess`

public class ActiveTextEnterField extends Object implements CSProcess
A specialisation of `ActiveTextField` that writes text to the `event` channel only when ENTER or ESCAPE is pressed.

## Process Diagram

## Description

`ActiveTextEnterField` is a process containing an ``ActiveTextField``, 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 `ActiveTextField` is that text is only written to the `event` channel when ENTER or ESCAPE is pressed on the text field (not on every keystroke). When this happens, the text field is temporarilly disabled for (by default) half a second; this is to give feedback to the user. The disable period can be changed by calling the `setDisableTime` method before the process is run.

The internal `ActiveTextField` can be extracted with the `getActiveTextField` 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 myTextFieldEvent = Channel.one2one (new OverWriteOldestBuffer (n));

       final ActiveTextEnterField myTextEnterField =
         new ActiveTextEnterField (null, myTextFieldEvent.out (), "Edit 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 | Set the text in this `ActiveTextEnterField` to the value of the `String`

Boolean

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

ActiveTextField.Configure | Invoke the user-defined `Configure.configure` method on the textField.
otherwise | Append the `toString` form of the object to the text in this `ActiveTextField`.
Output Channels
event | String | The text in the `ActiveTextEnterField` (whenever ENTER or ESCAPE is pressed)
componentEvent | ComponentEvent | See the ``getActiveTextField``.``addComponentEventChannel`` method.
focusEvent | FocusEvent | See the ``getActiveTextField``.``addFocusEventChannel`` method.
keyEvent | KeyEvent | See the ``getActiveTextField``.``addKeyEventChannel`` method.
mouseEvent | MouseEvent | See the ``getActiveTextField``.``addMouseEventChannel`` method.
mouseMotionEvent | MouseEvent | See the ``getActiveTextField``.``addMouseMotionEventChannel`` method.

## Example

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

     public class ActiveTextEnterFieldExample {

       public static void main (String argv[]) {

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

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

         final String[] string =
           {"Entia Non Sunt Multiplicanda Praeter Necessitatem",
            "Less is More ... More or Less",
            "Everything we do, we do it to you",
            "Race Hazards - What Rice Hozzers?",
            "Cogito Ergo Occam"};

         final String goodbye = "Goodbye World";

         final ActiveTextEnterField[] activeText =
           new ActiveTextEnterField[string.length];

         for (int i = 0; i invalid input: '<' string.length; i++) {
           activeText[i] = new ActiveTextEnterField (null, event.out (), string[i]);
         }

         Panel panel = new Panel (new GridLayout (string.length, 1));
         for (int i = 0; i invalid input: '<' string.length; i++) {
           panel.add (activeText[i].getActiveTextField ());
         }

         final Frame realFrame = frame.getActiveFrame ();
         realFrame.setBackground (Color.green);
         realFrame.add (panel);
         realFrame.pack ();
         realFrame.setVisible (true);

         new Parallel (
           new CSProcess[] {
             frame,
             new Parallel (activeText),
             new CSProcess () {
               public void run () {
                 boolean running = true;
                 while (running) {
                   String s = (String) event.in ().read ();
                   System.out.println (s);
                   running = (! s.equals (goodbye));
                 }
                 realFrame.setVisible (false);
                 System.exit (0);
               }
             }
           }
         ).run ();
       }

     }

Author:
  P.D. Austin and P.H. Welch
See Also:
  - `ActiveTextField`
  - `TextField`
  - `ComponentEvent`
  - `FocusEvent`
  - `KeyEvent`
  - `MouseEvent`
  - `OverWriteOldestBuffer`

## Constructor Summary

Constructors
Constructor
Description
`ActiveTextEnterField(AltingChannelInput configure, ChannelOutput event)`
Constructs a new `ActiveTextEnterField` with configuration and event channels, but no initial text.
`ActiveTextEnterField(AltingChannelInput configure, ChannelOutput event, String s)`
Constructs a new `ActiveTextEnterField` with configuration and event channels, initial text and default width.
`ActiveTextEnterField(AltingChannelInput configure, ChannelOutput event, String s, int columns)`
Constructs a new `ActiveTextEnterField` with configuration and event channels, initial text and width.

## Method Summary

Modifier and Type
Method
Description
`ActiveTextField`
`getActiveTextField()`
This is used to get the `ActiveTextField` within this component so that it can be configured (using `TextField` or `ActiveTextField` methods) or added to some container.
`void`
`run()`
The main body of this process.
`void`
`setConfigureChannel(AltingChannelInput configure)`
Sets the configuration channel for this `ActiveTextEnterField`.
`void`
`setDisableTime(long disableTime)`
This is used to set the time during which the text field is disabled after an ENTER or ESCAPE has been entered.

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

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

## Constructor Details

### ActiveTextEnterField

public ActiveTextEnterField(AltingChannelInput configure, ChannelOutput event)
Constructs a new `ActiveTextEnterField` with configuration and event channels, but no initial text.

Parameters:
  `configure` - the AltingChannelInput for configuration events -- can be null if no configuration is required.
  `event` - the current text will be output when the ENTER or ESCAPE key is pressed -- can be null if no notification is required.

### ActiveTextEnterField

public ActiveTextEnterField(AltingChannelInput configure, ChannelOutput event, String s)
Constructs a new `ActiveTextEnterField` with configuration and event channels, initial text and default width.

Parameters:
  `configure` - the AltingChannelInput for configuration events -- can be null if no configuration is required.
  `event` - the current text will be output when the ENTER or ESCAPE key is pressed -- can be null if no notification is required.
  `s` - the initial text displayed in the field.

### ActiveTextEnterField

public ActiveTextEnterField(AltingChannelInput configure, ChannelOutput event, String s, int columns)
Constructs a new `ActiveTextEnterField` with configuration and event channels, initial text and width.

Parameters:
  `configure` - the AltingChannelInput for configuration events -- can be null if no configuration is required.
  `event` - the current text will be output when the ENTER or ESCAPE key is pressed -- can be null if no notification is required.
  `s` - the initial text displayed in the field.
  `columns` - the width of the field.

## Method Details

### setConfigureChannel

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

### setDisableTime

public void setDisableTime(long disableTime)
This is used to set the time during which the text field is disabled after an ENTER or ESCAPE has been entered.

NOTE: This may only be called before this process is run.

Parameters:
  `disableTime` - the disable time after an ENTER or ESCAPE.

### getActiveTextField

public ActiveTextField getActiveTextField()
This is used to get the `ActiveTextField` within this component so that it can be configured (using `TextField` or `ActiveTextField` methods) or added to some container. For example, event channels can be added by invoking `getActiveTextField().add` XXX `EventChannel(...)`.

NOTE: such configuration must be finished before this process is run.

NOTE: do not use this method to set a configure channel - use an appropriate constructor or `setConfigureChannel`.

Returns:
  the `ActiveTextField` within this component.

### run

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

Specified by:
  `run` in interface `CSProcess`