BOOPSI Images

Introduction

BOOPSI's imageclass is one of the standard classes built into Intuition. As its name implies, it is a class of Intuition Images. These BOOPSI images can be used in place of traditional Image structure (as they contain an Intuition Image structure), but they are much more powerful. By using BOOPSI methods, an application or Intuition can tell an imageclass object to render itself. Because it renders itself (rather than Intuition rendering it), the imageclass object is free to render whatever it wants (well, within reason). For example, a BOOPSI image object can render itself according to the current display resolution, or to scale itself to any size an application requests.

BOOPSI Image Methods

Imageclass defines several methods of its own which subclasses of imageclass either have to implement or pass on to their superclass. The method IDs for imageclass are defined in <intuition/imageclass.h>. Each method requires some parameters.

Method	Description
IM_DRAW	Draw image with state.
IM_DRAWFRAME	Draw image within frame limits.
IM_ERASE	Erase image with state.
IM_ERASEFRAME	Erase image within frame.
IM_HITFRAME	Determine if image was hit within frame.
IM_HITTEST	Determine if image was hit.

The following methods are described at the imageclass level although it's up to the subclasses to actually implement them. If a class does not implement these methods it should either return zero, indicating that this class does not support the method, or defer processing on to its superclass.

Method	Description
IM_FRAMEBOX	Get recommended frame around some box.
IM_EXTENT	Inquire about rendering extent.
IM_EXTENTFRAME	Inquire about rendering extent with dimensions.

The formats of each of these BOOPSI messages all differ. The MethodID is the only parameter common to each method.

IM_DRAW

The IM_DRAW method is used to tell the image to render itself. The Intuition function DrawImageState() uses this method. IM_DRAW receives the following parameters:

struct impDraw
{
    uint32 MethodID;
    struct RastPort *imp_RPort;
    struct
    {
        int16 X;
        int16 Y;
    } imp_Offset;
 
    uint32 imp_State;
    struct DrawInfo *imp_DrInfo;
};

The imp_State field contains the visual state to render the image. The visual states (defined in <intuition/imageclass.h>) are:

IDS_NORMAL	idle state
IDS_SELECTED	for selected gadgets.
IDS_DISABLED	for disabled gadgets.
IDS_BUSY	for future functionality
IDS_INDETERMINATE	for future functionality
IDS_INACTIVENORMAL	normal, in inactive window border.
IDS_INACTIVESELECTED	selected, in inactive border.
IDS_INACTIVEDISABLED	disabled, in inactive border.

When setting the pens to render an image, use the values from the imp_DrInfo->dri_Pens pen array (Note that it is possible that imp_DrInfo will be NULL). The possible pen values are defined in <intuition/screens.h>.

The following code fragment shows how to use the shadow color for rendering.

uint16 *pens = (imp->imp_DrInfo) ? imp->imp_DrInfo->dri_Pens : NULL;
 
if (pens)
{
    IIntuition->SetAPen (imp->imp_RPort, pens[SHADOWPEN]);
}

IM_ERASE

The IM_ERASE method tells an image to erase itself. The Intuition function EraseImage() uses this method. IM_ERASE receives the following parameters:

struct impErase
{
    uint32 MethodID;
    struct RastPort *imp_RPort;
    struct
    {
        int16 X;
        int16 Y;
    } imp_Offset;
};

The mytextlabelclass example doesn't know anything about this method, so it blindly passes this message on to the superclass. The superclass, imageclass, will call the graphics.library function EraseRect() using the dimensions found in the imageclass object's Image structure.

IM_ERASEFRAME

The IM_ERASEFRAME method instructs an image confined to a given rectangle to erase itself. Normally this method is used to erase an image drawn using the IM_DRAWFRAME method. This method expects the following parameters:

struct impErase
{
    uint32 MethodID;
    struct RastPort *imp_RPort;
    struct
    {
        int16 X;
        int16 Y;
    } imp_Offset;
 
    /* these parameters only valid for IM_ERASEFRAME */
    struct
    {
        int16 Width;
        int16 Height;
    } imp_Dimensions;
};

The mytextlabelclass example blindly passes this method on to its superclass. The superclass treats IM_ERASEFRAME just like IM_ERASE.

IM_DRAWFRAME

The IM_DRAWFRAME method instructs the image to render itself within the confines of the given rectangle. It receives the following parameters:

struct impDraw
{
    uint32 MethodID;
    struct RastPort *imp_RPort;
    struct
    {
        int16 X;
        int16 Y;
    } imp_Offset;
 
    uint32 imp_State;
    struct DrawInfo *imp_DrInfo;
 
    struct
    {
        int16 Width;
        int16 Height;
    } imp_Dimensions;
};

The Width and Height fields provide the object's rectangular bounds. How the image object deals with the frame is implementation specific. Typically, a scaleable image will scale itself as best it can to fit into the rectangle. The mytextlabelclass.c example does not actually implement this method, instead mytextlabelclass treats IM_DRAWFRAME like the IM_DRAW method.

In general, applications that use this method to draw an object should use the IM_ERASEFRAME method (see below) to erase it. This will ensure that the image was erased at the proper scale.