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.
This interface following defines the following types:
- String
- An alias for the ilu.CString type.
- Data
- An alias for the SEQUENCE OF BYTE type.
This interface defines the following exceptions:
- ImageError
- An image cannot be displayed.
- AuthorizationFailed
- A decryption key was required but not set.
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.
- 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.
- 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.
- 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.