Package org.jcsp.plugNplay

# Class FramedButtonGrid

java.lang.Object
org.jcsp.plugNplay.FramedButtonGrid

All Implemented Interfaces:
  `CSProcess`

public final class FramedButtonGrid extends Object implements CSProcess
A free-standing grid of button processes in their own frame, with configure and event channels.

## Process Diagram

Please check out the process diagram for a framed single button in `FramedButton`. Imagine here a 2D grid of these, each with individual configure and event channels.

## Description

This process provides a free-standing grid of button processes in their own frame. They are just `ActiveButton`s wrapped in an `ActiveClosingFrame`, but save us the trouble of constructing them.

Wire them to application processes with configure channels (for setting labels, enabling/disabling and all other configuration options) and event channels (on which the current label on any button is sent when that button is clicked). Note that all the events may be streamed to the same channel, provided an `Any2*Channel` is used (as in the example below).

Initially, all button labels are empty `java.lang.String`s. To set a button label, send a `java.lang.String` down the appropriate configure channel.

Initially, all buttons are enabled. To disable a button, send `java.lang.Boolean.FALSE` down the appropriate configure channel. To enable, send `java.lang.Boolean.TRUE`.

For other configuration options, send objects implementing the `ActiveButton.Configure` interface.

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 myButtonEvent =
         Channel.one2one (new OverWriteOldestBuffer (n));

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.

## Example

This runs a framed button grid in parallel with a simple application process (in-lined in the ``Parallel`` below). All event channels from the buttons are mulitplexed through an `Any2OneChannel` to the application process. The application configures the buttons with their labels, then reports each time any of them is pressed. The application ends when the button labelled `Goodbye World' is pressed.

     import org.jcsp.lang.*;
     import org.jcsp.util.*;
     import org.jcsp.plugNplay.*;

     public class FramedButtonGridExample {

       public static void main (String argv[]) {

         // labels for the grid of buttons

         final String[][] label = {
           new String[] {"Java", "occam-pi", "Handel-C"},
           new String[] {"C", "C++", "C#"},
           new String[] {"Haskell", "Modula", "Goodbye World"}
         };

         final int nDown = label.length;
         final int nAcross = label[0].length;

         // initial pixel sizes for the frame for the grid of buttons

         final int pixDown = 20 + (nDown*100);
         final int pixAcross = nAcross*120;

         // all button events are wired (for this example) to the same channel ...

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

         final Any2OneChannel[][] event = new Any2OneChannel[nDown][nAcross];

         for (int i = 0; i invalid input: '<' nDown; i++) {
           for (int j = 0; j invalid input: '<' nAcross; j++) {
             event[i][j] = allEvents;
           }
         }

         // make the grid of buttons (each one separately configured) ...

         final One2OneChannel[][] configure = new One2OneChannel[nDown][nAcross];

         for (int i = 0; i invalid input: '<' nDown; i++) {
           configure[i] = Channel.one2oneArray (nAcross);
         }

         final ChannelInput[][] configureIn = new ChannelInput[nDown][nAcross];
         final ChannelOutput[][] eventOut = new ChannelOutput[nDown][nAcross];

         for (int i = 0; i invalid input: '<' nDown; i++) {
           configureIn[i] = Channel.getInputArray (configure[i]);
           eventOut[i] = Channel.getOutputArray (event[i]);
         }

         final FramedButtonGrid grid =
           new FramedButtonGrid (
             "FramedButtonGrid Demo", nDown, nAcross,
             pixDown, pixAcross, configureIn, eventOut
           );

         // testrig ...

         new Parallel (

           new CSProcess[] {

             grid,

             new CSProcess () {

               public void run () {

                 for (int i = 0; i invalid input: '<' nDown; i++) {
                   for (int j = 0; j invalid input: '<' nAcross; j++) {
                     configure[i][j].out ().write (label[i][j]);
                   }
                 }

                 boolean running = true;
                 while (running) {
                   final String s = (String) allEvents.in ().read ();
                   System.out.println ("Button `" + s + "' pressed ...");
                   running = (s != label[nDown - 1][nAcross - 1]);
                 }

                 System.exit (0);

               }

             }

           }
         ).run ();

       }

     }

Author:
  P.H. Welch
See Also:
  - `ActiveButton`
  - `FramedButton`
  - `FramedButtonArray`
  - `FramedScrollbar`

## Constructor Summary

Constructors
Constructor
Description
`FramedButtonGrid(String title, int nDown, int nAcross, int pixDown, int pixAcross, ChannelInput[][] configure, ChannelOutput[][] event)`
Construct a framed button grid process.

## Method Summary

Modifier and Type
Method
Description
`void`
`run()`
This defines the actions of the process.

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

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

## Constructor Details

### FramedButtonGrid

public FramedButtonGrid(String title, int nDown, int nAcross, int pixDown, int pixAcross, ChannelInput[][] configure, ChannelOutput[][] event)
Construct a framed button grid process.

Parameters:
  `title` - the title for the frame (must not be null)
  `nDown` - the number of buttons down in the grid (must be at least 1)
  `nAcross` - the number of buttons across in the grid (must be at least 1)
  `pixDown` - the pixel hieght of the frame (must be at least 100)
  `pixAcross` - the pixel width of the frame (must be at least 100)
  `configure` - the matrix of configure channels for the buttons (must not be null)
  `event` - the matrix of event channels from the buttons (must not be null)

## Method Details

### run

public void run()
Description copied from interface: `CSProcess`
This defines the actions of the process.

Specified by:
  `run` in interface `CSProcess`