Copyright (c) Hyperion Entertainment and contributors.
BOOPSI Images
Contents
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_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.
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 impEraseFrame { 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_HITFRAME
The IM_HITFRAME method is used to determine if a point is within an image that is contained within (or scaled to) the given rectangle. This method is intended to test images that were rendered using IM_DRAWFRAME. This method receives the following parameters:
struct impHitFrame { uint32 MethodID; struct { int16 X; int16 Y; } imp_Point; struct { int16 Width; int16 Height; } imp_Dimensions; };
The mytextlabelclass example blindly passes this method on to its superclass. The superclass treat this meothd just like the IM_HITTEST method.
IM_HITTEST
IM_HITTEST returns true if a point is within the image. The Intuition function PointInImage() uses this method. IM_HITTEST requires the following parameters:
struct impHitTest { uint16 MethodID; struct { int16 X; int16 Y; } imp_Point; };
The mytextlabelclass example blindly passes this method on to its superclass. The superclass, imageclass, will return TRUE if the point is within the old Image structure box.
IM_FRAMEBOX
The IM_FRAMEBOX method returns size information for an image (usually some sort of frame image). The following parameters are associated with the IM_FRAMEBOX method.
struct impFrameBox { uint32 MethodID; struct IBox *imp_ContentsBox; /* Application supplied IBox for the result */ struct IBox *imp_FrameBox; /* Rectangle to frame */ struct DrawInfo *imp_DrInfo; uint32 imp_FrameFlags; };
This method is used to ask the image what size it would like to be, if it had to frame the rectangle in the imp_FrameBox field. This method normally applies only to image classes that put a frame around some object (like frameiclass). By passing the dimensions and position of a rectangle, the framing image determines the position and size it should be to properly "frame" the object bounded by the imp_FrameBox rectangle. IM_FRAMEBOX stores the result in the IBox structure pointed to by imp_ContentsBox. This method allows an application to use a framing image without having to worry about image specific details such as accounting for the thickness of the frame or centering the frame around the object.
The imp_FrameFlags field is a bit field used to specify certain options for the IM_FRAMEBOX method. Currently, there is only one defined for it, FRAMEF_SPECIFY. If this bit is set, IM_FRAMEBOX has to use the width and height supplied to it in the imp_FrameBox field (even if these are too small!) as the frame dimensions. It can only adjust its position, typically to center the object as best as possible.
This method is not supported by the mytextlabelclass example. It passes this message to its superclass which does not support this method either. When the message returns from the superclass, the return value will be zero, indicating to the application that this method is not supported.
Examples
usemyIC.c
<syntaxhighlighting> /*
* usemyIC.c * * Originally written by David N. Junod */
- include <exec/types.h>
- include <exec/libraries.h>
- include <intuition/intuition.h>
- include <intuition/classes.h>
- include <intuition/classusr.h>
- include <intuition/cghooks.h>
- include <intuition/gadgetclass.h>
- include <intuition/imageclass.h>
- include <graphics/gfx.h>
- include <graphics/gfxmacros.h>
- include <libraries/gadtools.h>
- include <utility/tagitem.h>
- include <clib/macros.h>
- include <clib/exec_protos.h>
- include <clib/dos_protos.h>
- include <clib/intuition_protos.h>
- include <clib/graphics_protos.h>
- include <clib/utility_protos.h>
- include <string.h>
extern struct Library *SysBase, *DOSBase; struct Library *IntuitionBase, *GfxBase, *UtilityBase;
Class *initmyTextLabelClass(VOID); ULONG freemyTextLabelClass(Class * cl);
VOID main(VOID) {
Class *cl; struct Image *im; struct Window *win; struct RastPort *rp; UWORD top, left, height;
/* Make sure we're at least using Version 2.0 */
if (IntuitionBase = OpenLibrary("intuition.library", 36))
{
GfxBase = OpenLibrary("graphics.library", 36);
UtilityBase = OpenLibrary("utility.library", 36);
/* Open a window, without system gadgets or IDCMP events */
if (win = OpenWindowTags(NULL,
WA_Left, 10,
WA_Top, 10,
WA_Width, 320,
WA_Height, 100,
TAG_DONE))
{
/* Cache the pointer to the RastPort */
rp = win->RPort;
/* Cache the upper-left coordinates of the window */
top = win->BorderTop + INTERHEIGHT;
left = win->BorderRight + INTERWIDTH;
/* Cache the height of the font */
height = rp->TxHeight + INTERHEIGHT;
/* Initialize the custom image class. */
if (cl = initmyTextLabelClass())
{
/* Create a new image structure, using the given string. */
if (im = NewObject(cl, NULL,
IA_Data, (ULONG) "Line _1",
TAG_DONE))
{
/* Paint using the provided text string. */
DrawImageState(rp, im, left, top,
IDS_NORMAL, NULL);
/* Replace the text string, and paint it. */
im->ImageData = (USHORT *) "Line _2";
DrawImageState(rp, im, left, top + height,
IDS_NORMAL, NULL);
/* Replace the text string, and paint it. */
im->ImageData = (USHORT *) "Line _3";
DrawImageState(rp, im, left, top + (height * 2),
IDS_NORMAL, NULL);
/* Free the image. */
DisposeObject(im);
}
/* Free the image class. */
freemyTextLabelClass(cl);
}
Delay(250);
CloseWindow(win);
}
CloseLibrary(UtilityBase);
CloseLibrary(GfxBase);
CloseLibrary(IntuitionBase);
}
} </syntaxhighlighting>
mytextlabelclass.c
/* * Original code written by David N. Junod * * The Image structure as used by this class: * * struct Image { * * SHORT LeftEdge; <----Offset relative to the container * SHORT TopEdge; * * SHORT Width; <----Contains the text extent of the string * SHORT Height; * * SHORT Depth; <----Maintained by boopsi (must be set to CUSTOMIMAGEDEPTH). * * USHORT *ImageData; <----Pointer to a NULL terminated text string * * UBYTE PlanePick; <----We use this for the foreground color * * UBYTE PlaneOnOff; <----We use this for the background color * * struct Image *NextImage; <----Pointer to the next image. Handled by DrawImage(). }; */ #include <exec/types.h> #include <exec/memory.h> #include <exec/libraries.h> #include <intuition/intuition.h> #include <intuition/classes.h> #include <intuition/classusr.h> #include <intuition/cghooks.h> #include <intuition/gadgetclass.h> #include <intuition/imageclass.h> #include <intuition/icclass.h> #include <intuition/screens.h> #include <graphics/gfx.h> #include <graphics/gfxmacros.h> #include <libraries/gadtools.h> #include <utility/tagitem.h> #include <proto/exec.h> #include <proto/intuition.h> #include <proto/graphics.h> #include <proto/utility.h> extern struct Library *IntuitionBase, *GfxBase, *UtilityBase; /* * Because we are dealing with imageclass objects, the data structure that makes up the * object is an intuition Image structure. */ #define IM(o) ((struct Image *)(o)) #define MYCLASSID NULL #define SUPERCLASSID (IMAGECLASS) Class *initmyTextLabelClass(VOID); ULONG freemyTextLabelClass(Class * cl); ULONG dispatchmyTextLabel(Class * cl, Object * o, Msg msg); ULONG setmyTextLabelAttrs(Class * cl, Object * o, struct opSet * msg); ULONG getmyTextLabelAttr(Class * cl, Object * o, struct opGet * msg); ULONG drawmyTextLabel(Class * cl, Object * o, struct impDraw * msg); WORD aTextExtent(struct RastPort *, STRPTR, LONG, struct TextExtent *); UWORD GetLabelKeystroke(STRPTR label); static VOID getContentsExtent(Class * cl, Object * o, struct DrawInfo * drinfo); /* prototypes of functions from classface.o */ ULONG DoMethod(Object * o, ULONG methodID,...); ULONG DoSuperMethod(Class * cl, Object * o, ULONG methodID,...); ULONG CoerceMethod(Class * cl, Object * o, ULONG methodID,...); ULONG CM(Class * cl, Object * o, Msg msg); ULONG DM(Object * o, Msg msg); ULONG DSM(Class * cl, Object * o, Msg msg); ULONG SetSuperAttrs(Class * cl, Object * o, ULONG data,...); struct localObjData { /* Font to use */ struct TextFont *lod_Font; /* The key that is underlined */ UWORD lod_Key; /* DrawMode */ UBYTE lod_Mode; }; Class *initmyTextLabelClass(VOID) { Class *cl; if (cl = IIntuition->MakeClass(MYCLASSID, SUPERCLASSID, NULL, sizeof(struct localObjData), 0)) { /* Fill in the callback hook */ cl->cl_Dispatcher.h_Entry = dispatchmyTextLabel; } /* Return a pointer to the class */ return (cl); } ULONG freemyTextLabelClass(Class * cl) { /* Try to free the public class */ return ((ULONG) IIntuition->FreeClass(cl)); } ULONG dispatchmyTextLabel(Class * cl, Object * o, Msg msg) { struct localObjData *lod; Object *newobj; ULONG retval; switch (msg->MethodID) { case OM_NEW: /* Pass up to the superclass... */ if (newobj = (Object *) DSM(cl, o, msg)) { struct TagItem *attrs = ((struct opSet *) msg)->ops_AttrList; struct DrawInfo *drinfo; /* Get the DrawInfo */ drinfo = (struct DrawInfo *) IUtility->GetTagData(SYSIA_DrawInfo, NULL, attrs); /* Get the instance data */ lod = INST_DATA(cl, newobj); /* Establish defaults */ IM(newobj)->PlanePick = 1; lod->lod_Mode = JAM1; /* Set the attributes */ setmyTextLabelAttrs(cl, newobj, (struct opSet *) msg); /* Get the bounding rectangle of the label */ getContentsExtent(cl, newobj, drinfo); } retval = (ULONG) newobj; break; case OM_GET: retval = getmyTextLabelAttr(cl, o, (struct opGet *) msg); break; case OM_UPDATE: case OM_SET: /* Do the superclass first */ retval = DSM(cl, o, msg); /* Call our set routines */ retval += setmyTextLabelAttrs(cl, o, (struct opSet *) msg); break; case IM_DRAW: /* draw the label */ case IM_DRAWFRAME: /* drawmyTextLabel() will take care of extra framing info */ retval = drawmyTextLabel(cl, o, (struct impDraw *) msg); break; /* Let the superclass handle everything else */ default: retval = (ULONG) DSM(cl, o, msg); break; } return (retval); } /* Set attributes of an object */ ULONG setmyTextLabelAttrs(Class * cl, Object * o, struct opSet * msg) { struct localObjData *lod = INST_DATA(cl, o); struct TagItem *tags = msg->ops_AttrList; struct TagItem *tstate; struct TagItem *tag; ULONG tidata; /* process rest */ tstate = tags; while (tag = NextTagItem(&tstate)) { tidata = tag->ti_Data; switch (tag->ti_Tag) { case IA_FGPen: IM(o)->PlanePick = (UBYTE) tidata; break; case IA_BGPen: IM(o)->PlaneOnOff = (UBYTE) tidata; break; /* Must be a TextFont pointer. */ case IA_Font: /* Set the font */ lod->lod_Font = (struct TextFont *) tidata; break; /* Drawing mode to use */ case IA_Mode: lod->lod_Mode = (UBYTE) tidata; break; case IA_Data: IM(o)->ImageData = (USHORT *) tidata; lod->lod_Key = GetLabelKeystroke((STRPTR) tidata); break; } } return (1L); } /* Inquire attributes of an object */ ULONG getmyTextLabelAttr(Class * cl, Object * o, struct opGet * msg) { struct localObjData *lod = INST_DATA(cl, o); switch (msg->opg_AttrID) { case IA_Font: *msg->opg_Storage = (ULONG) lod->lod_Font; break; case IA_Mode: *msg->opg_Storage = (ULONG) lod->lod_Mode; break; /* Let the superclass try */ default: return ((ULONG) DSM(cl, o, msg)); } return (1L); } ULONG drawmyTextLabel(Class * cl, Object * o, struct impDraw * msg) { struct localObjData *lod = INST_DATA(cl, o); STRPTR label = (STRPTR) IM(o)->ImageData; struct DrawInfo *di = msg->imp_DrInfo; struct RastPort *rp = msg->imp_RPort; struct TextFont *tf = NULL; WORD len = strlen(label); WORD left, top; WORD height = 0; WORD width = 0; WORD i; /* Clear the key */ lod->lod_Key = NULL; /* Get a pointer to the font to use */ if (!(tf = lod->lod_Font) && di) { tf = di->dri_Font; } /* Make sure we have font pointer */ if (tf) { /* Set the font */ IGraphics->SetFont(rp, tf); } /* Figure out our coordinates */ top = msg->imp_Offset.Y + IM(o)->TopEdge + rp->TxBaseline; left = msg->imp_Offset.X + IM(o)->LeftEdge; /* See if we have frame information. */ if (msg->MethodID == IM_DRAWFRAME) { /* Center the text inside the frame. */ width = msg->imp_Dimensions.Width; height = msg->imp_Dimensions.Height; top += ((height - IM(o)->Height) > 0) ? ((height - IM(o)->Height) / 2) : 0; left += ((width - IM(o)->Width) > 0) ? ((width - IM(o)->Width) / 2) : 0; } /* Set the colors */ IGraphics->SetAPen(rp, IM(o)->PlanePick); IGraphics->SetBPen(rp, IM(o)->PlaneOnOff); /* Set the drawing mode */ IGraphics->SetDrMd(rp, lod->lod_Mode); /* Move to the start */ IGraphics->Move(rp, left, top); /* Step through string */ for (i = 0; i < (len - 1); i++) { /* Is this an '_' ? */ if (label[i] == '_') { WORD bot = (top + rp->TxHeight - rp->TxBaseline); WORD mark; /* Draw the first part of the string */ IGraphics->Text(rp, label, i); /* Remember where we are in the string */ mark = rp->cp_x; /* Draw the underscore */ IGraphics->Move(rp, mark, bot); IGraphics->Draw(rp, (mark + IGraphics->TextLength(rp, &label[(i + 1)], 1L) - 2), bot); /* Return to where we were */ IGraphics->Move(rp, mark, top); /* * Draw the rest of the string. This one is done last so that the cursor * could be positioned after the text. */ IGraphics->Text(rp, &label[(i + 1)], (len - i - 1)); /* Return the underlined character */ lod->lod_Key = (UWORD) label[i]; } } /* Do we have an underscore? */ if (!lod->lod_Key) { /* Didn't find an '_' sign */ Text(rp, label, len); } return (1L); } UWORD GetLabelKeystroke(STRPTR label) { LONG count = (label) ? strlen(label) : 0L; LONG i; /* Search for an _ sign */ for (i = 0; i < (count - 1); i++) { /* Did we find an _ sign? */ if (label[i] == '_') { return ((UWORD) label[(i + 1)]); } } return (0); } /* TextExtent that honors the '_' as being a non-printable character (once) */ WORD aTextExtent(struct RastPort * rp, STRPTR string, LONG count, struct TextExtent * te) { WORD retval = FALSE; STRPTR buffer; LONG i; /* Allocate a temporary buffer */ if (buffer = IExec->AllocVecTags((count + 1), AVT_ClearWithValue, 0, TAG_END)) { /* Step through string */ for (i = 0; i < count; i++) { /* Is this an '_' sign? */ if (string[i] == '_') { /* Add the rest of the label to the buffer */ strcat (buffer, &string[(i + 1)]); /* Adjust the length of the string. */ count--; break; } else { /* Copy each character over, until we reach the _ mark */ buffer[i] = string[i]; } } /* Get the extent */ IGraphics->TextExtent(rp, buffer, count, te); /* Free the temporary buffer */ IExec->FreeVec (buffer); /* Show that we were successful */ retval = TRUE; } /* Return whatever textextent returned */ return (retval); } static VOID getContentsExtent(Class * cl, Object * o, struct DrawInfo * drinfo) { struct localObjData *lod = INST_DATA(cl, o); struct TextExtent te = {NULL}; struct RastPort rp; STRPTR label; /* maybe look at some flags to handle other types of text someday */ if (label = (STRPTR) IM(o)->ImageData) { /* Initialize the RastPort */ IGraphics->InitRastPort(&rp); if (lod->lod_Font) { IGraphics->SetFont(&rp, lod->lod_Font); } else if (drinfo && drinfo->dri_Font) { IGraphics->SetFont(&rp, drinfo->dri_Font); } /* Get the rectangle for the label */ aTextExtent(&rp, label, strlen(label), &te); /* Set the image structure */ IM(o)->Width = te.te_Width; IM(o)->Height = te.te_Height; } else { IM(o)->Width = IM(o)->Height = 0; } }
