Interface Specification for SimpleIOAPI

Overview

The simpleio plugin provides a GUI interface for console I/O. The SimpleIOAPI interface defines the interface to this plugin. When a KP requests a new I/O window from the plugin, the plugin pops up a window on the console of the KSS where the plugin is run.

The plugin can be used by KPs that want to interact with a user in a slightly more fancy way than the shell window that's normally used for a KP's standard console. It can also be used by KPs that want to interact with different users at different KSSs, or by KPs that need user input but are started from rs (which currently only provides output).

See the User Interface section below for a description of the interface from the user's point of view.

See the iotools module for an interface that uses the simpleio plugin if available and falls back on the KP's standard console otherwise.

Imported Interfaces

SimpleIO imports the FileAPI interface.

Type Definitions

This interface defines only one type, String, an alias for the ilu.CString type.

Exceptions

This interface defines only one exception type, SpawnError, which is raised when an I/O window could not be created. The value of the exception is a string describing the problem in more detail.

Objects

This interface defines the following object type:

SimpleIOFactory

A factory to create new I/O windows. The plugin registers a service of this type (i.e., SimpleIOAPI.SimpleIOFactory) under the name simpleio.

Methods

This interface defines the following object methods:

SimpleIOFactory methods

GetNewSimpleIO() : FileAPI.File

Create an I/O window on the screen, with a default width and height. The I/O window object is a FileAPI.File type object. Raise SpawnError if the I/O window could not be created.

GetNewSimpleIOWH(height : INTEGER, width : INTEGER) : FileAPI.File

Create an I/O window on the the screen, with the specified width and height. The I/O window object is a FileAPI.File type object. Raise SpawnError if the I/O window could not be created.

User Interface

Here is an overview of the user interface provided by the simpleio plugin.

Figure 1. The SimpleIO GUI window

The window is divided in two text areas; output from the KP is displayed in the top area, and input from the user is typed in the bottom area. When the KP is requesting input, the label above the input area contains the message KP is reading.... When the KP is not requesting input but the user has typed some text ahead, the message displayed is (lines in buffer: N ), where N is the number of lines typed by the user but not yet read by the KP.

The controls speak for themselves: Clear Input Buffer discards any type-ahead, Clear Output Log empties the output window, and Quit closes the window. If the KP tries to read from the window after it has been closed, it will receive an ilu.IluGeneralError exception.