Interface Specification for PlayerAPI

Overview

The Player plugin provides a GUI interface for displaying images. The PlayerAPI interface defines the interface for this plugin as well as for other image display services, e.g. a KP providing display services for encrypted images.

Images can be of any supported format. Tk itself supports only GIF images natively. The plugin supports JPEG images through conversion to GIF via the helper program djpeg. See the installation manual for details.

Types

This interface following defines the following types:

String

An alias for the ilu.CString type.

Data

An alias for the SEQUENCE OF BYTE type.

Exceptions

This interface defines the following exceptions:

ImageError

An image cannot be displayed.

AuthorizationFailed

A decryption key was required but not set.

Objects

This interface defines the following object types:

ImagePlayer

Basic object for displaying an image.

DecryptPlayer

An extension of the ImagePlayer object (i.e. it has a ImagePlayer as a SUPERTYPE), this object adds one new method, and overrides one method. Its purpose is to provide for display of encrypted images, given a proper decryption key. Note: the Player plugin does not implement this object type; it is defined in this interface so that e.g. an image decryption KP can implement it.

PlayerFactory

This factory object creates new ImagePlayer instances. The Player plugin registers a service of this type (i.e., PlayerAPI.PlayerFactory) under the name PlayerFactory.

ImagePlayer Objects

SetImageName (name : String)

Images can have names, which are displayed in the Tk window as a label underneath the image. This method sets that name.

SetImageData (image : Data)

This sets the object's image data to the specified sequence of bytes. This data is the complete image data in it's raw form, including image header information.

Play ()

This method instructs the object to display the image data and image name in a Tk window. Figure 1 illustrates the type of image window that is displayed.

Figure 1. Tk image window

It can raise the ImageError exception if the image data was never set with SetImageData(), or the image data was corrupt. In this case, Play() will still pop up a Tk window; figure 2 illustrates what this looks like.

Figure 2. Corrupt image data window

Close ()

Closes the image window. This is equivalent to the user hitting the Close button on the Tk window.

DecryptPlayer Objects

SetImageKey (key : Data)

Set the decryption key for the image. The decryption key is a sequence of bytes. It is up to the DecryptPlayer object to implement the algorithm used to combine the encrypted image data (set via the ImagePlayer's SetImageData method) and the decryption key.

Play ()

This method overrides the ImagePlayer's method. It adds a second exception, AuthorizationFailed, raised when no decryption key was set. If an invalid decryption key was given, the ImageError exception will likely be raised.

PlayerFactory Objects

GetNewPlayer() : ImagePlayer

Create a new ImagePlayer instance. Note that depending on the implementation of the PlayerFactory, the actual object returned could be of type DecryptPlayer. Run-time type identification is required to make the distinction, if necessary.