AmigaOS Documentation Wiki - User contributions [en]

BOOPSI Images

2024-09-10T12:10:45Z

Frédéric Khannouf: /* mytextlabelclass.c */ Removed some useless definitions. Some cleaning and type castings

== 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.

{| class="wikitable"
! 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.

{| class="wikitable"
! 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:

<syntaxhighlight>
struct impDraw
{
uint32 MethodID;
struct RastPort *imp_RPort;
struct
{
int16 X;
int16 Y;
} imp_Offset;

uint32 imp_State;
struct DrawInfo *imp_DrInfo;
};
</syntaxhighlight>

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

{| class="wikitable"
| 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.

<syntaxhighlight>
uint16 *pens = (imp->imp_DrInfo) ? imp->imp_DrInfo->dri_Pens : NULL;

if (pens)
{
IIntuition->SetAPen (imp->imp_RPort, pens[SHADOWPEN]);
}
</syntaxhighlight>

=== IM_DRAWFRAME ===

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

<syntaxhighlight>
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;
};
</syntaxhighlight>

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:

<syntaxhighlight>
struct impErase
{
uint32 MethodID;
struct RastPort *imp_RPort;
struct
{
int16 X;
int16 Y;
} imp_Offset;
};
</syntaxhighlight>

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:

<syntaxhighlight>
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;
};
</syntaxhighlight>

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:

<syntaxhighlight>
struct impHitFrame
{
uint32 MethodID;
struct
{
int16 X;
int16 Y;
} imp_Point;

struct
{
int16 Width;
int16 Height;
} imp_Dimensions;
};
</syntaxhighlight>

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:

<syntaxhighlight>
struct impHitTest
{
uint16 MethodID;
struct
{
int16 X;
int16 Y;
} imp_Point;
};
</syntaxhighlight>

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.

<syntaxhighlight>
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;
};
</syntaxhighlight>

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 ===

The example code initializes and uses a custom imageclass object. Notice that usemyIC.c directly manipulates fields within the Image structure embedded within the BOOPSI imageclass object. This is legal for image classes whose immediate superclass is imageclass (for the LeftEdge, TopEdge, Width, Height, ImageData, PlanePick, and PlaneOnOff Image structure fields only; the other Image structure fields are off limits). Indirect subclasses of imageclass may not alter the values in the embedded Image structure as future direct subclasses of imageclass may need to know about changes to values in the Image structure.

<syntaxhighlight>
/*
* 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 <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>
#include <proto/graphics.h>
#include <proto/utility.h>
#include <string.h>

struct IntuitionIFace *IIntuition = NULL;

Class *initmyTextLabelClass(VOID);
ULONG freemyTextLabelClass(Class * cl);

int main()
{
Class *cl;
struct Image *im;
struct Window *win;

struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
struct Library *GfxBase = IExec->OpenLibrary("graphics.library", 50);

IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);
IGraphics = (struct GraphicsIFace*)IExec->GetInterface(GfxBase, "main", 1, NULL);

if (IIntuition != NULL && IGraphics != NULL)
{
/* Open a window, without system gadgets or IDCMP events */
if (win = IIntuition->OpenWindowTags(NULL,
WA_Left, 10,
WA_Top, 10,
WA_Width, 320,
WA_Height, 100,
TAG_END))
{
/* Cache the pointer to the RastPort */
struct RastPort *rp = win->RPort;

/* Cache the upper-left coordinates of the window */
uint16 top = win->BorderTop + INTERHEIGHT;
uint16 left = win->BorderRight + INTERWIDTH;

/* Cache the height of the font */
uint16 height = rp->TxHeight + INTERHEIGHT;

/* Initialize the custom image class. */
if (cl = initmyTextLabelClass())
{
/* Create a new image structure, using the given string. */
if (im = IIntuition->NewObject(cl, NULL,
IA_Data, (ULONG) "Line _1",
TAG_END))
{
/* Paint using the provided text string. */
IIntuition->DrawImageState(rp, im, left, top,
IDS_NORMAL, NULL);

/* Replace the text string, and paint it. */
im->ImageData = (USHORT *) "Line _2";
IIntuition->DrawImageState(rp, im, left, top + height,
IDS_NORMAL, NULL);

/* Replace the text string, and paint it. */
im->ImageData = (USHORT *) "Line _3";
IIntuition->DrawImageState(rp, im, left, top + (height * 2),
IDS_NORMAL, NULL);

/* Free the image. */
IIntuition->DisposeObject(im);
}

/* Free the image class. */
freemyTextLabelClass(cl);
}

IDOS->Delay(250);
IIntuition->CloseWindow(win);
}
}

IExec->DropInterface((struct Interface*)IGraphics);
IExec->DropInterface((struct Interface*)IIntuition);
IExec->CloseLibrary(GfxBase);
IExec->CloseLibrary(IntuitionBase);

return 0;
}
</syntaxhighlight>

=== mytextlabelclass.c ===

The image class example code, mytextlabelclass.c, illustrates a complete custom image class. This image class provides an application with textual labels that have a particular character underlined. This is useful for indicating which key controls a gadget (although the example provided only utilizes imageclass objects; there are no gadgets involved).

A custom image can be used in the place of any standard Intuition Image structure. For example, an application can attach an imageclass object to: the GadgetRender and SelectRender fields of a Gadget structure (defined in <intuition/intuition.h>), the ReqImage field of a Requester structure, or even the ItemFill field of the MenuItem structure.

<syntaxhighlight>
/*
* Original code written by David N. Junod
*
* The Image structure as used by this class:
*
* struct Image {
*
* int16 LeftEdge; <----Offset relative to the container
* int16 TopEdge;
*
* int16 Width; <----Contains the text extent of the string
* int16 Height;
*
* int16 Depth; <----Maintained by BOOPSI (must be set to CUSTOMIMAGEDEPTH).
*
* Uint16 *ImageData; <----Pointer to a NULL terminated text string
*
* uint8 PlanePick; <----We use this for the foreground color
*
* uint8 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 IntuitionIFace *IIntuition;
extern struct GraphicsIFace *IGraphics;

/*
* 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);
uint32 freemyTextLabelClass(Class * cl);
uint32 dispatchmyTextLabel(Class * cl, Object * o, Msg msg);
uint32 setmyTextLabelAttrs(Class * cl, Object * o, struct opSet * msg);
uint32 getmyTextLabelAttr(Class * cl, Object * o, struct opGet * msg);
uint32 drawmyTextLabel(Class * cl, Object * o, struct impDraw * msg);
int16 aTextExtent(struct RastPort *, STRPTR, LONG, struct TextExtent *);
uint16 GetLabelKeystroke(STRPTR label);
static VOID getContentsExtent(Class * cl, Object * o, struct DrawInfo * drinfo);

struct localObjData
{
/* Font to use */
struct TextFont *lod_Font;

/* The key that is underlined */
uint16 lod_Key;

/* DrawMode */
uint8 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 = (HOOKFUNC)dispatchmyTextLabel;
}
/* Return a pointer to the class */
return (cl);
}

uint32 freemyTextLabelClass(Class * cl)
{
/* Try to free the public class */
return ((uint32) IIntuition->FreeClass(cl));
}

uint32 dispatchmyTextLabel(Class * cl, Object * o, Msg msg)
{
struct localObjData *lod;
Object *newobj;
uint32 retval;

switch (msg->MethodID)
{
case OM_NEW:
/* Pass up to the superclass... */
if ((newobj = (Object *) IIntuition->IDoSuperMethodA(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 = (struct localObjData *)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 = (uint32) newobj;
break;

case OM_GET:
retval = getmyTextLabelAttr(cl, o, (struct opGet *) msg);
break;

case OM_UPDATE:
case OM_SET:
/* Do the superclass first */
retval = IIntuition->IDoSuperMethodA(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 = (uint32) IIntuition->IDoSuperMethodA(cl, o, msg);
break;
}

return (retval);
}

/* Set attributes of an object */
uint32 setmyTextLabelAttrs(Class * cl, Object * o, struct opSet * msg)
{
struct localObjData *lod = (struct localObjData *)INST_DATA(cl, o);
struct TagItem *tags = msg->ops_AttrList;
struct TagItem *tstate;
struct TagItem *tag;
uint32 tidata;

/* process rest */
tstate = tags;
while ((tag = IUtility->NextTagItem(&tstate)))
{
tidata = tag->ti_Data;
switch (tag->ti_Tag)
{
case IA_FGPen:
IM(o)->PlanePick = (uint8) tidata;
break;

case IA_BGPen:
IM(o)->PlaneOnOff = (uint8) 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 = (uint8) tidata;
break;

case IA_Data:
IM(o)->ImageData = (uint16 *) tidata;
lod->lod_Key = GetLabelKeystroke((STRPTR) tidata);
break;
}
}

return (1L);
}

/* Inquire attributes of an object */
uint32 getmyTextLabelAttr(Class * cl, Object * o, struct opGet * msg)
{
struct localObjData *lod = (struct localObjData *)INST_DATA(cl, o);

switch (msg->opg_AttrID)
{
case IA_Font:
*msg->opg_Storage = (uint32) lod->lod_Font;
break;

case IA_Mode:
*msg->opg_Storage = (uint32) lod->lod_Mode;
break;

/* Let the superclass try */
default:
return ((uint32) IIntuition->IDoSuperMethodA(cl, o, (Msg)msg));
}

return (1L);
}

uint32 drawmyTextLabel(Class * cl, Object * o, struct impDraw * msg)
{
struct localObjData *lod = (struct localObjData *)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;
int16 len = strlen(label);
int16 left, top;
int16 height = 0;
int16 width = 0;
int16 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] == '_')
{
int16 bot = (top + rp->TxHeight - rp->TxBaseline);
int16 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 = (uint16) label[i];
}
}

/* Do we have an underscore? */
if (!lod->lod_Key)
{
/* Didn't find an '_' sign */
IGraphics->Text(rp, label, len);
}
return (1L);
}

uint16 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 ((uint16) label[(i + 1)]);
}
}

return (0);
}

/* TextExtent that honors the '_' as being a non-printable character (once) */
int16 aTextExtent(struct RastPort * rp, STRPTR string, LONG count, struct TextExtent * te)
{
int16 retval = FALSE;
STRPTR buffer;
LONG i;

/* Allocate a temporary buffer */
if ((buffer = (STRPTR)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 = (localObjData *)INST_DATA(cl, o);
struct TextExtent te = {0, 0, {0, 0, 0, 0}};
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;
}
}
</syntaxhighlight>

BOOPSI Gadgets

2024-09-10T09:06:10Z

Frédéric Khannouf: /* RKMButtonclass.c */

=== Introduction ===

One of the major enhancements to Intuition is the implementation of customizable BOOPSI gadgets. BOOPSI gadgets are not limited by dependencies upon Intuition Image and Gadget structures. Unlike ordinary gadgets, which were handled exclusively by Intuition, BOOPSI gadgets handle their own rendering and their own user input.

Since BOOPSI gadgets draw themselves, there is almost no restriction on what they can look like. A BOOPSI gadget can use graphics.library RastPort drawing functions to draw vector-based imagery which the gadget can scale to any dimension. Instead of just a two-state Boolean gadget, a BOOPSI gadget can have any number of states, each of which has its own imagery. If a programmer wanted to he could even make a BOOPSI gadget that uses the animation system to render itself.

Because BOOPSI gadgets handle their own input, they see all the user's input, which the gadget is free to interpret. While the user has a BOOPSI gadget selected, the gadget can track mouse moves, process mouse and keyboard key presses, or watch the timer events.

The power of a BOOPSI gadget is not limited to its ability to handle its own rendering and user input. BOOPSI gadgets are also BOOPSI objects so the gain all the benefits BOOPSI provides. This means all BOOPSI gadgets inherit the methods and attributes from their superclasses. BOOPSI gadgets can use BOOPSI images to take care of rendering their imagery. A BOOPSI gadget could be a "composite" gadget that is composed of several BOOPSI gadgets, images, and models.

=== The BOOPSI Gadget Methods ===

Intuition drives a BOOPSI gadget by sending it BOOPSI messages. Intuition uses the following BOOPSI methods:

{| class="wikitable"
! Method !! Description
|-
| GM_DOMAIN || Obtain gadget sizing requirements.
|-
| GM_EXTENT || Inquire about rendering extent. (V51)
|-
| GM_GOACTIVE || This method asks a gadget if it wants to be the active gadget.
|-
| GM_GOINACTIVE || This method tells a gadget that it is no longer active.
|-
| GM_HANDLEINPUT || This method passes a gadget an input event.
|-
| GM_HELPTEST || Determine if gadget help was hit.
|-
| GM_HITTEST || This method asks a gadget whether it has been "hit" by a mouse click.
|-
| GM_LAYOUT || Calculate relative gadget coordinates.
|-
| GM_RENDER || This method tells the gadget to render itself.
|}

The formats of each of these BOOPSI messages differ, but they all have two things in common. Like all BOOPSI messages, each starts with their respective method ID. For each of these methods, the method ID field is followed by a pointer to a GadgetInfo structure (defined in <intuition/cghooks.h>). The GadgetInfo structure contains information about the display on which the gadget needs to render itself:

<syntaxhighlight>
struct GadgetInfo {
struct Screen *gi_Screen;
struct Window *gi_Window; /* null for screen gadgets */
struct Requester *gi_Requester; /* null if not GTYP_REQGADGET */

/* rendering information: don't use these without cloning/locking.
* Official way is to call ObtainGIRPort()
*/
struct RastPort *gi_RastPort;
struct Layer *gi_Layer;

/* copy of dimensions of screen/window/g00/req(/group)
* that gadget resides in. Left/Top of this box is
* offset from window mouse coordinates to gadget coordinates
* screen gadgets: 0,0 (from screen coords)
* window gadgets (no g00): 0,0
* GTYP_GZZGADGETs (borderlayer): 0,0
* GZZ innerlayer gadget: borderleft, bordertop
* Requester gadgets: reqleft, reqtop
*/
struct IBox gi_Domain;

/* these are the pens for the window or screen */
struct {
UBYTE DetailPen;
UBYTE BlockPen;
} gi_Pens;

/* the Detail and Block pens in gi_DrInfo->dri_Pens[] are
* for the screen. Use the above for window-sensitive colors.
*/
struct DrawInfo *gi_DrInfo;

/* reserved space: this structure is extensible
* anyway, but using these saves some recompilation
*/
ULONG gi_Reserved[6];
};
</syntaxhighlight>

All the fields in this structure are read only.

Although this structure contains a pointer to the gadget's RastPort structure, applications should not use it for rendering. Instead, use the intuition.library function ObtainGIRPort() to obtain a copy of the GadgetInfo's RastPort. When the gadget is finished with this RastPort, it should call ReleaseGIRPort() to relinquish the RastPort.

==== GM_DOMAIN ====

Intuition uses the GM_DOMAIN method to determine the basic sizing requirements of an object. The domain is most often used by layout gadgets to aid in distributing the gadgets within the layout via GM_LAYOUT. The GM_DOMAIN method uses the gpDomain structure (defined in <intuition/gadgetclass.h>) as its message:

<syntaxhighlight>
struct gpDomain
{
uint32 MethodID;
struct GadgetInfo *gpd_GInfo;
struct RastPort *gpd_RPort; /* RastPort to layout for */
int32 gpd_Which;
struct IBox gpd_Domain; /* Resulting domain */
struct TagItem *gpd_Attrs; /* Additional attributes */
};
</syntaxhighlight>

The gpd_Which field is used to determine which domain the caller is interested in: GDOMAIN_MINIMUM, GDOMAIN_NOMINAL or GDOMAIN_MAXIMUM. The object is expected to fill in the provided gpd_Domain with the width and height dimensions. The location coordinates are not used. The gpd_Attrs pointer, if not NULL, may contain additional tags which are defined on a per-class basis.

==== GM_EXTENT (V51) ====

The GM_EXTENT method is used to ask the gadget what pixels (at least) it will fully redraw when its GM_RENDER method is invoked in the same context. By "fully redraw" we mean changing the pixel's color in a way that is totally unrelated to its previous value -- so this doesn't apply to alpha-blended pixels for example.

Intuition uses that information for optimization purposes. During GUI refreshes, it will skip filling or erasing those pixels that the gadget would then completely re-render anyway. Supporting this method in your gadgets will help Intuition improve the smoothness of user interface refresh by preventing redundant graphic calls and minimizing "flicker" effects caused by background clearing especially during window resizes.

===== Simple Support =====

The easiest way to support GM_EXTENT is to make sure your gadget always fills every pixel within its dimensions and just return the relevant result value (GMR_FULLHBOX or GMR_FULLBBOX). In this case, you may safely ignore the actual message contents and the following text.

If the above solution is not feasible (for instance because the gadget has an irregular or not fully connected shape) then you should check the gpe_Region and gpe_RPort message fields: if any of them is non-NULL you may decide to employ a more detailed way to tell the caller exactly what pixels your GM_RENDER method does fill.

===== Region and RastPort Support =====

If gpe_Region is non-NULL you can compose in it your gadget's shape by using graphics.library's XxxxRectRegion() functions. Remember to look at the gpe_Action field to determine what function to use. For example, if gpe_Action is GEXTENT_ADD you should use OrRectRegion(). Note you must NOT pre-clear or alter the initial region's contents in any way other than to compose your own gadget's shape. Once finished composing your gadget's shape in the region, return GMR_CLIPDONE to let the caller know you updated the region's contents.

If gpe_RPort is non-NULL you can draw your gadget's shape into it just like you would do for a GM_RENDER message -- however, you're only allowed to use colors 0 or 1 because you're actually drawing into a single-bitplane mask. Again, check the gpe_Action field to find out whether you should actually set, clear or invert the pixels making up your gadget's shape in the mask. You are not allowed to alter any pixels other than those belonging to your gadget's shape nor to clear the mask's background before rendering. Once finished drawing your gadget's shape in the mask plane return GMR_MASKDONE to let the caller know you updated the mask's contents.

If both gpe_Region and gpe_RPort are non-NULL you may simply choose the method which is most suited for your purposes. You don't have to support both for the same message. If you do, however, you can let the caller know by ORing together the appropriate return values. The region solution is best suited for gadgets made up of a few rectangular parts whereas the mask method is better in the case of more complex gadget shapes.

===== Images =====

If all or part of your gadget's rendering is performed by some BOOPSI image you could also try asking the image for its extent information by way of an IM_EXTENT or IM_EXTENTFRAME message (see [[BOOPSI_Images|BOOPSI Images]]).

If for whatever reasons your GM_EXTENT method finds itself unable to support any of the described solutions it should return GMR_INVALID. This particular return value will tell Intuition not to clip away the gadget's shape at all. While this is usually slower and more prone to flickering it will still produce correct graphic results. This is the same fallback applied for any gadgets not recognizing the GM_EXTENT method.

===== Superclass Extent Handling =====

Since it is very important that a gadget's GM_RENDER and GM_EXTENT methods remain synchronized the default behavior of a gadget class should be to only handle GM_EXTENT if it is the "true class" of the object the method is invoked on and just return GMR_INVALID otherwise. This is because a subclass might override the behavior of GM_RENDER in such a way that your class' GM_EXTENT results are no longer correct.

If a gadget subclass needs and knows it's ok to let its superclass handle GM_EXTENT it must set the GPEF_ALLOWSUPER flag in gpe_Flags before calling IDoSuperMethodA() and clear it as soon as the call returns. If GPEF_ALLOWSUPER is set in gpe_Flags your gadget should accept and handle GM_EXTENT regardless of whether it is the true class or not.

{{Note|text=As of Intuition V51 the mask method is not yet implemented.}}

==== GM_GOACTIVE/GM_HANDLEINPUT ====

If a gadget returns GMR_GADGETHIT, Intuition will send it a GM_GOACTIVE message (defined in <intuition/gadgetclass.h>):

<syntaxhighlight>
struct gpInput /* Used by GM_GOACTIVE and GM_HANDLEINPUT */
{
ULONG MethodID;
struct GadgetInfo *gpi_GInfo;
struct InputEvent *gpi_IEvent; /* The input event that triggered this method
* (for GM_GOACTIVE, this can be NULL) */
LONG *gpi_Termination; /* For GADGETUP IntuiMessage.Code */
struct
{
WORD X; /* Mouse position relative to upper */
WORD Y; /* left corner of gadget (LeftEdge, TopEdge) */
} gpi_Mouse;
};
</syntaxhighlight>

The GM_GOACTIVE message gives a gadget the opportunity to become the active gadget. The active gadget is the gadget that is currently receiving user input. Under normal conditions, only one gadget can be the active gadget (it is possible to have more than one active gadget using a groupgclass object (See the [[BOOPSI_Class_Reference|BOOPSI Class Reference]] for more details).

While a gadget is active, Intuition sends it GM_HANDLEINPUT messages. Each GM_HANDLEINPUT message corresponds to a single InputEvent structure. These InputEvents can be keyboard presses, timer events, mouse moves, or mouse button presses. The message's gpi_IEvent field points to this InputEvent structure. It's up to the GM_HANDLEINPUT method to interpret the meaning of these events and update the visual state of the gadget as the user manipulates the gadget. For example, the GM_HANDLEINPUT method of a prop gadget has to track mouse events to see where the user has moved the prop gadget's knob and update the gadget's imagery to reflect the new position of the knob.

For the GM_GOACTIVE method, the gpi_IEvent field points to the struct InputEvent that triggered the GM_GOACTIVE message. Unlike the GM_HANDLEINPUT message, GM_GOACTIVE's gpi_IEvent can be NULL. If the GM_GOACTIVE message was triggered by a function like intuition.library's ActivateGadget() and not by a real InputEvent (like the user clicking the gadget), the gpi_IEvent field will be NULL.

For gadgets that only want to become active as a direct result of a mouse click, this difference is important. For example, the prop gadget becomes active only when the user clicks on its knob. Because the only way the user can control the prop gadget is via the mouse, it does not make sense for anything but the mouse to activate the gadget. On the other hand, a string gadget doesn't care how it is activated because, as soon as it's active, it gets user input from the keyboard rather than the mouse. Not all gadgets can become active. Some gadgets cannot become active because they have been temporarily disabled (their Gadget.Flags GFLG_DISABLED bit is set). Other gadgets will not become active because they don't need to process input. For example, a toggle gadget won't become active because it only needs to process one input event, the mouse click that toggles the gadget (which it gets from the GM_GOACTIVE message). If a toggle gadget gets a GM_GOACTIVE message and its gpi_IEvent field is not NULL, it will toggle its state and refuse to "go active".

The GM_GOACTIVE method has to take care of any visual state changes to a gadget that a GM_GOACTIVE message might trigger. For example, the toggle gadget in the previous paragraph has to take care of toggling its visual state from selected imagery to unselected imagery. If the gadget goes through a state change when it becomes the active gadget, (like when a string gadget positions its cursor) GM_GOACTIVE has to take care of this.

===== Return Values =====

The return values of both GM_GOACTIVE and GM_HANDLEINPUT tell Intuition whether or not the gadget wants to be active. A gadget's GM_GOACTIVE method returns GMR_MEACTIVE (defined in <intuition/gadgetclass.h>) if it wants to become the active gadget. A gadget's GM_HANDLEINPUT method returns GMR_MEACTIVE if it wants to remain the active gadget. If a gadget either does not want to become or remain the active gadget, it returns one of the "go inactive" return values:

; GMR_NOREUSE
: Tells Intuition to throw away the gpInput.gpi_IEvent InputEvent.

; GMR_REUSE
: Tells Intuition to process the gpInput.gpi_IEvent InputEvent.

; GMR_NEXTACTIVE
: Tells Intuition to throw away the gpInput.gpi_IEvent InputEvent and activate the next GFLG_TagCycle gadget.

; GMR_PREVACTIVE
: Tells Intuition to throw away the gpInput.gpi_IEvent InputEvent and activate the previous GFLG_TagCycle gadget.

GMR_NOREUSE tells Intuition that the gadget does not want to be active and to throw away the InputEvent that triggered the message. For example, an active prop gadget returns GMR_NOREUSE when the user lets go of the left mouse button (thus letting go of the prop gadget's knob).

For the GM_HANDLEINPUT method, a gadget can also return GMR_REUSE, which tells Intuition to reuse the InputEvent. For example, if the user clicks outside the active string gadget, that string gadget returns GMR_REUSE. Intuition can now process that mouse click, which can be over another gadget. Another case where a string gadget returns GMR_REUSE is when the user pushes the right mouse button (the menu button). The string gadget becomes inactive and the menu button InputEvent gets reused. Intuition sees this event and tries to pop up the menu bar.

For the GM_GOACTIVE method, a gadget must not return GMR_REUSE. If a gadget gets a GM_GOACTIVE message from Intuition and the message has an gpi_IEvent, the message was triggered by the user clicking on the gadget. In this case, Intuition knows that the user is trying to select the gadget. Intuition doesn't know if the gadget can be activated, but if it can be activated, the event that triggered the activation has just taken place. If the gadget cannot become active for any reason, it must not let Intuition reuse that InputEvent as the gadget has already taken care of the the event's purpose (clicking on the gadget). In essence, the user tried to activate the gadget and the gadget refused to become active.

The other two possible return values are GMR_NEXTACTIVE and GMR_PREVACTIVE. These tell Intuition that a gadget does not want to be active and that the InputEvent should be discarded. Intuition then looks for the next (GMR_NEXTACTIVE) or previous (GMR_PREVACTIVE) gadget that has its GFLG_TABCYCLE flag set in its Gadget.Activation field (see the gadgetclass GA_TabCycle attribute in the [[BOOPSI_Class_Reference|BOOPSI Class Reference]]).

For both GM_GOACTIVE and GM_HANDLEINPUT, the gadget can bitwise-OR any of these "go inactive" return values with GMR_VERIFY. The GMR_VERIFY flag tells Intuition to send a GADGETUP IntuiMessage to the gadget's window. If the gadget uses GMR_VERIFY, it has to supply a value for the IntuiMessage.Code field. It does this by passing a value in the gpInput.gpi_Termination field. This field points to a long word, the lower 16-bits of which Intuition copies into the Code field. The upper 16-bits are for future enhancements, so clear these bits.

==== GM_GOINACTIVE ====

After an active gadget deactivates, Intuition sends it a GM_GOINACTIVE message (defined in <intuition/gadgetclass.h>):

<syntaxhighlight>
struct gpGoInactive
{
ULONG MethodID; /* GM_GOINACTIVE */
struct GadgetInfo *gpgi_GInfo;
ULONG gpgi_Abort; /* gpgi_Abort=1 if gadget was aborted by Intuition */
/* and 0 if gadget went inactive at its own request. */
};
</syntaxhighlight>

The gpgi_Abort field contains either a 0 or 1. If 0, the gadget became inactive on its own power (because the GM_GOACTIVE or GM_HANDLEINPUT method returned something besides GMR_MEACTIVE). If gpgi_Abort is 1, Intuition aborted this active gadget. Some instances where Intuition aborts a gadget include: the user clicked in another window or screen, an application removed the active gadget with RemoveGList(), and an application called ActiveWindow() on a window other than the gadget's window.

==== GM_HELPTEST ====

This method uses the same message structure as GM_HITTEST, struct gpHitTest, and operates similarly to GM_HITTEST. While a window is in help mode, when the user positions the pointer within the bounding box of a BOOPSI gadget that supports gadget help, Intuition sends the gadget a GM_HELPTEST message. After an active gadget deactivates, Intuition sends it a GM_GOINACTIVE message.

<syntaxhighlight>
struct gpHitTest
{
uint32 MethodID; // GM_HELPTEST
struct GadgetInfo *gpht_GInfo;
struct
{
int16 X; // Is this point inside
int16 Y; // gadget?
} gpht_Mouse;
};
</syntaxhighlight>

Like the GM_HITTEST method, the GM_HELPTEST method asks a gadget if a point is within the gadget's bounds. Like the GM_HITTEST method, the GM_HELPTEST method allows a BOOPSI gadget to have a non-rectangular hit area (or in this case, a help area). If the point is within the gadget, the gadget uses one of two return codes. If the gadget returns a value of GMR_HELPHIT, Intuition places a value of 0xFFFF in the Code field of the IDCMP_GADGETHELP message. The gadget also has the option of using GMR_HELPCODE instead of GMR_HELPHIT. GMR_HELPCODE is a little peculiar as a return value. Although GMR_HELPCODE is 32 bits long, Intuition identifies GMR_HELPCODE using only its upper 16 bits. If the upper 16 bits of GM_HELPTEST's return value matches the upper 16 bits of GMR_HELPCODE, Intuition copies the lower word of the return value into the Code field of the IDCMP_GADGETHELP message. The BOOPSI gadget is free to set the return value's lower word to any 16-bit value.

If the point is not within the gadget's "help spot", the gadget returns GMR_NOHELPHIT. Intuition will then look under that gadget for more gadgets. If a gadget's dispatcher passes the GM_HELPTEST method on to the gadgetclass dispatcher, the gadgetclass dispatcher
will always return GMR_HELPHIT.

An application can put several windows in the same help group. This feature groups several windows so that as long as one of those windows is active, the application can receive IDCMP_GADGETHELP messages about all of those windows. For more information, See the HelpControl() Autodoc and the WA_HelpGroup section of the OpenWindow() Autodoc (both are in intuition.doc).

==== GM_HITTEST ====

When Intuition gets a left mouse button click in a window, one of the things it does is check through the window's list of gadgets to see if that click was inside the bounds of a gadget's Gadget structure (using the LeftEdge, TopEdge, Width, and Height fields). If it was (and that gadget is a BOOPSI gadget), Intuition sends that gadget a GM_HITTEST message (defined in <intuition/gadgetclass.h>):

<syntaxhighlight>
struct gpHitTest
{
uint32 MethodID; // GM_HITTEST
struct GadgetInfo *gpht_GInfo;
struct
{
int16 X; // Is this point inside
int16 Y; // gadget?
} gpht_Mouse;
};
</syntaxhighlight>

This message contains the coordinates of the mouse click. These coordinates are relative to the upper-left of the gadget (LeftEdge, TopEdge).

Because Intuition can only tell if the user clicked inside gadget's "bounding box", Intuition only knows that the click was close to the gadget. Intuition uses the GM_HITTEST to ask the gadget if the click was really inside the gadget. The gadget returns GMR_GADGETHIT (defined in <intuition/gadgetclass.h>) to tell Intuition that the user hit it, otherwise it returns zero. This method allows a gadget to be any shape or pattern, rather than just rectangular.

==== GM_LAYOUT ====

Intuition uses the GM_LAYOUT method to tell a GREL BOOPSI gadget that its window's dimensions have changed. The GM_LAYOUT method uses the gpLayout structure (defined in <intuition/gadgetclass.h>) as its message:

<syntaxhighlight>
struct gpLayout
{
uint32 MethodID;
struct GadgetInfo *gpl_GInfo;
uint32 gpl_Initial; /* This field is non-zero if this method was invoked
* during AddGList() or OpenWindow(). zero if this
* method was invoked during window resizing.
*/
};
</syntaxhighlight>

For GREL gadgets, Intuition sends a GM_LAYOUT message just after erasing the gadget's bounding box. Intuition does not touch the values of the gadget's bounding box or hit box, it lets the gadget handle recalculating these values. The gadget can lay itself out based on the new window (or requester) dimensions found in the GadgetInfo structure passed in the GM_LAYOUT message (gpl_GInfo from the gpLayout structure). Intuition also adds the old and new bounding box of the gadget to the window's damaged regions so that the gadget will appear is its new position. The gadget must not perform any rendering inside the GM_LAYOUT method. Intuition will send a GM_RENDER message to the gadget when its time to redraw the gadget in its new position.

There are two cases where Intuition sends a GM_LAYOUT message:
# When the gadget's window is resized
# When Intuition adds the gadget to a window

For most GREL BOOPSI gadgets, Intuition expects the values in the LeftEdge, TopEdge, Width, and Height fields to follow the existing convention for regular GREL gadgets. Each of these fields has a flag in the Gadget.Flags field (GFLG_RELRIGHT, GFLG_RELBOTTOM, GFLG_RELWIDTH, and GFLG_RELHEIGHT, respectively). If that field's flag is set, Intuition expects the value in that field to be relative to either the window border or the window dimensions. For example, if GFLG_RELRIGHT is set, Intuition expects the value in the gadget's LeftEdge field to be relative to the right window border.

There is a special kind of GREL BOOPSI gadget called a custom relativity gadget. For this type of gadget, Intuition expects the values in the LeftEdge, TopEdge, Width, and Height fields to be absolute measurements, just like the values Intuition expects in these fields for non-GREL gadgets.

Setting the GFLG_RELSPECIAL bit in the Gadget.Flags field marks the gadget as a custom relativity gadget. The best way to set this bit is by setting the GA_RelSpecial attribute to TRUE when creating the gadget.

==== GM_RENDER ====

Every time Intuition feels it is necessary to redraw a BOOPSI gadget, it sends a gadget a GM_RENDER message. The GM_RENDER message (defined in <intuition/gadgetclass.h>) tells a gadget to render itself:

<syntaxhighlight>
struct gpRender
{
uint32 MethodID; /* GM_RENDER */
struct GadgetInfo *gpr_GInfo;
struct RastPort *gpr_RPort; /* all ready for use */
int32 gpr_Redraw; /* might be a "highlight pass" */
};
</syntaxhighlight>

Some events that cause Intuition to send a GM_RENDER are: an application passed the gadget to OpenWindow(), the user moved or resized a gadget's window, or an application explicitly asked Intuition to refresh some gadgets.

The GM_RENDER message contains a pointer to the gadget's RastPort so the GM_RENDER method does not have to extract it from the gpr_GInfo GadgetInfo structure using ObtainGIRPort()). The gadget renders itself according to how much imagery it needs to replace. The gpr_Redraw field contains one of three values:

{| class="wikitable"
| GREDRAW_REDRAW
| Redraw the entire gadget.
|-
| GREDRAW_UPDATE
| The user has manipulated the gadget, causing a change to its imagery. Update only that part of the gadget's imagery that is effected by the user manipulating the gadget (for example, the knob and scrolling field of the prop gadget).
|-
| GREDRAW_TOGGLE
| If this gadget supports it, toggle to or from the highlighting imagery.
|}

Intuition is not the only entity that calls this method. The gadget's other methods may call this method to render the gadget when it goes through state changes. For example, as a prop gadget is following the mouse from the gadget's GM_HANDLEINPUT method, the gadget could send itself GM_RENDER messages, telling itself to update its imagery according to where the mouse has moved.

The DoRender() method should always be used by class implementers to invoke a GM_RENDER method on a gadget object. Applications use the RefreshGList() function which will invoke GM_RENDER for the caller in the proper context.

=== The Active Gadget ===

While a gadget is active, Intuition sends it a GM_HANDLEINPUT message for every timer pulse, mouse move, mouse click, and key press that takes place. A timer event pulse arrives about every tenth of a second. Mouse move events can arrive at a much higher rate than the timer pulses. Without even considering the keyboard, a gadget can get a lot of GM_HANDLEINPUT messages in a short amount of time. Because the active gadget has to handle a large volume of GM_HANDLEINPUT messages, the overhead of this method should be kept to a minimum.

Because the gadget will always receive a GM_GOACTIVE message before it is active and a GM_GOINACTIVE message after it is no longer active, the gadget can use these methods to allocate, initialize, and deallocate temporary resources it needs for the GM_HANDLEINPUT method. This can significantly reduce the overhead of GM_HANDLEINPUT because it eliminates the need to allocate, initialize, and deallocate resources for every GM_HANDLEINPUT message.

Note that the RastPort from ObtainGIRPort() is not cachable using this method. If the GM_HANDLEINPUT method needs to use a RastPort, it has to obtain and release the RastPort for every GM_HANDLEINPUT message using ObtainGIRPort() and ReleaseGIRPort().

=== RKMButtonclass.c ===

The following example is a sample BOOPSI gadget, RKMButClass.c.

While the user has the RKMButton selected, the gadget sends an OM_UPDATE message to its ICA_TARGET for every timer event the button sees.

The gadget sends notification about its RKMBUT_Pulse attribute, which is the horizontal distance in screen pixels the mouse is from the center of the button.
The gadget takes care of rendering all of its imagery (as opposed to using a BOOPSI image to do it).
The gadget's imagery is scalable to any dimensions and can be set (using SetGadgetAttrs()) while the gadget is in place.

One possible use for such a gadget is as buttons for a prop gadget.

If the user has the prop gadget's RKMButton selected, while the mouse is to the left of the button's center, the knob on the prop gadget moves left.
While the mouse is to the right of the button's center, the knob on the prop gadget moves right.
The speed at which the knob moves is proportional to the horizontal distance from the mouse to the active RKMButton.

<syntaxhighlight lang="cpp">
/* RKMButClass.c - Example BOOPSI gadget */

#include <exec/types.h>
#include <intuition/intuition.h>
#include <intuition/classes.h>
#include <intuition/classusr.h>
#include <intuition/imageclass.h>
#include <intuition/gadgetclass.h>
#include <intuition/cghooks.h>
#include <intuition/icclass.h>
#include <utility/tagitem.h>
#include <utility/hooks.h>

#include <proto/exec.h>
#include <proto/intuition.h>
#include <proto/graphics.h>
#include <proto/utility.h>

#include <graphics/gfxmacros.h>

CONST_STRPTR vers = "$VER: TestBut 50.1";

/***********************************************************/
/**************** Class specifics ****************/
/***********************************************************/
#define RKMBUT_Pulse (TAG_USER + 1)

struct ButINST
{
LONG midX, midY; /* Coordinates of middle of gadget */
};

/* ButINST has one flag: */
#define ERASE_ONLY 0x00000001 /* Tells rendering routine to */
/* only erase the gadget, not */
/* rerender a new one. This */
/* lets the gadget erase it- */
/* self before it rescales. */

/* The functions in this module */
Class *initRKMButGadClass(void);
BOOL freeRKMButGadClass(Class *);
ULONG dispatchRKMButGad(Class *, Object *, Msg);
void NotifyPulse(Class *, Object *, ULONG, LONG, struct gpInput *);
ULONG RenderRKMBut(Class *, struct Gadget *, struct gpRender *);
void MainLoop(ULONG, ULONG);

/*************************************************************************************************/
/* The main() function connects an RKMButClass object to a BOOPSI integer gadget, which displays */
/* the RKMButClass gadget's RKMBUT_Pulse value. The code scales and move the gadget while it is */
/* in place. */
/*************************************************************************************************/

struct TagItem pulse2int[] =
{
{RKMBUT_Pulse, STRINGA_LongVal},
{TAG_END,}
};

#define INTWIDTH 40
#define INTHEIGHT 20

struct IntuitionIFace *IIntuition;
struct GraphicsIFace *IGraphics;
struct Window *w;
Class *rkmbutcl;
struct Gadget *integer, *but;
struct IntuiMessage *msg;

int main(void)
{
struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
struct Library *GfxBase = IExec->OpenLibrary("graphics.library", 50);

IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);
IGraphics = (struct GraphicsIFace*)IExec->GetInterface(GfxBase, "main", 1, NULL);

if (IIntuition != NULL && IGraphics != NULL)
{
if (w = IIntuition->OpenWindowTags(NULL,
WA_Flags, WFLG_DEPTHGADGET | WFLG_DRAGBAR |
WFLG_CLOSEGADGET | WFLG_SIZEGADGET,
WA_IDCMP, IDCMP_CLOSEWINDOW,
WA_Width, 640,
WA_Height, 200,
TAG_END))
{
IIntuition->WindowLimits(w, 450, 200, 640, 200);

if (rkmbutcl = initRKMButGadClass())
{
if (integer = (struct Gadget *)IIntuition->NewObject(NULL,
"strgclass",
GA_ID, 1L,
GA_Top, (w->BorderTop) + 5L,
GA_Left, (w->BorderLeft) + 5L,
GA_Width, INTWIDTH,
GA_Height, INTHEIGHT,
STRINGA_LongVal, 0L,
STRINGA_MaxChars, 5L,
TAG_END))
{
if (but = (struct Gadget *)IIntuition->NewObject(rkmbutcl,
NULL,
GA_ID, 2L,
GA_Top, (w->BorderTop) + 5L,
GA_Left, integer->LeftEdge +
integer->Width + 5L,
GA_Width, 40L,
GA_Height, INTHEIGHT,
GA_Previous, integer,
ICA_MAP, pulse2int,
ICA_TARGET, integer,
TAG_END))
{
IIntuition->AddGList(w, integer, -1, -1, NULL);
IIntuition->RefreshGList(integer, w, NULL, -1);

IIntuition->SetWindowTitles(w,
"<-- Click to resize gadget Height",
NULL);
MainLoop(TAG_END, 0L);

IIntuition->SetWindowTitles(w,
"<-- Click to resize gadget Width",
NULL);
MainLoop(GA_Height, 100L);

IIntuition->SetWindowTitles(w,
"<-- Click to resize gadget Y position",
NULL);
MainLoop(GA_Width, 100L);

IIntuition->SetWindowTitles(w,
"<-- Click to resize gadget X position",
NULL);
MainLoop(GA_Top, but->TopEdge + 20);

IIntuition->SetWindowTitles(w,
"<-- Click to quit", NULL);
MainLoop(GA_Left, but->LeftEdge + 20);

IIntuition->RemoveGList(w, integer, -1);
IIntuition->DisposeObject((Object *)but);
}
IIntuition->DisposeObject((Object *)integer);
}
freeRKMButGadClass(rkmbutcl);
}
IIntuition->CloseWindow(w);
}
}

IExec->DropInterface((struct Interface*)IGraphics);
IExec->DropInterface((struct Interface*)IIntuition);
IExec->CloseLibrary(GfxBase);
IExec->CloseLibrary(IntuitionBase);

return 0;
}

void MainLoop(ULONG attr, ULONG value)
{
ULONG done = FALSE;

IIntuition->SetGadgetAttrs(but, w, NULL, attr, value, TAG_END);

while (done == FALSE)
{
IExec->WaitPort((struct MsgPort *)w->UserPort);
while (msg = (struct IntuiMessage *)
IExec->GetMsg((struct MsgPort *)w->UserPort))
{
if (msg->Class == IDCMP_CLOSEWINDOW)
{
done = TRUE;
}
IExec->ReplyMsg((Message *)msg);
}
}
}

/***********************************************************/
/** Make the class and set up the dispatcher's hook **/
/***********************************************************/
Class *initRKMButGadClass(void)
{
Class *cl = NULL;
extern ULONG HookEntry(); /* defined in amiga.lib */

if ( cl = IIntuition->MakeClass( NULL,
"gadgetclass", NULL,
sizeof ( struct ButINST ),
0 ))
{
/* initialize the cl_Dispatcher Hook */
cl->cl_Dispatcher.h_Entry = (HOOKFUNC)dispatchRKMButGad;
}
return ( cl );
}

/***********************************************************/
/****************** Free the class ****************/
/***********************************************************/
BOOL freeRKMButGadClass(Class *cl)
{
return IIntuition->FreeClass(cl);
}

/***********************************************************/
/********** The RKMBut class dispatcher *********/
/***********************************************************/
ULONG dispatchRKMButGad(Class *cl, Object *o, Msg msg)
{
struct ButINST *inst;
ULONG retval = FALSE;
Object *object;

switch (msg->MethodID)
{
case OM_NEW: /* First, pass up to superclass */
if (object = (Object *)IIntuition->IDoSuperMethodA(cl, o, msg))
{
struct Gadget *g = (struct Gadget *)object;

/* Initial local instance data */
inst = (ButINST *)INST_DATA(cl, object);
inst->midX = g->LeftEdge + ( (g->Width) / 2);
inst->midY = g->TopEdge + ( (g->Height) / 2);

retval = (ULONG)object;
}
break;
case GM_HITTEST:
/* Since this is a rectangular gadget this */
/* method always returns GMR_GADGETHIT. */
retval = GMR_GADGETHIT;
break;
case GM_GOACTIVE:
inst = (ButINST*)INST_DATA(cl, o);

/* Only become active if the GM_GOACTIVE */
/* was triggered by direct user input. */
if (((struct gpInput *)msg)->gpi_IEvent)
{
/* This gadget is now active, change */
/* visual state to selected and render. */
((struct Gadget *)o)->Flags |= GFLG_SELECTED;
RenderRKMBut(cl, (struct Gadget *)o, (struct gpRender *)msg);
retval = GMR_MEACTIVE;
}
else /* The GM_GOACTIVE was not */
/* triggered by direct user input. */
retval = GMR_NOREUSE;
break;
case GM_RENDER:
retval = RenderRKMBut(cl, (struct Gadget *)o, (struct gpRender *)msg);
break;
case GM_HANDLEINPUT: /* While it is active, this gadget sends its superclass an */
/* OM_NOTIFY pulse for every IECLASS_TIMER event that goes by */
/* (about one every 10th of a second). Any object that is */
/* connected to this gadget will get A LOT of OM_UPDATE messages. */
{
struct Gadget *g = (struct Gadget *)o;
struct gpInput *gpi = (struct gpInput *)msg;
struct InputEvent *ie = gpi->gpi_IEvent;

inst = (ButINST*)INST_DATA(cl, o);

retval = GMR_MEACTIVE;

if (ie->ie_Class == IECLASS_RAWMOUSE)
{
switch (ie->ie_Code)
{
case SELECTUP: /* The user let go of the gadget so return GMR_NOREUSE */
/* to deactivate and to tell Intuition not to reuse */
/* this Input Event as we have already processed it. */

/*If the user let go of the gadget while the mouse was */
/*over it, mask GMR_VERIFY into the return value so */
/*Intuition will send a Release Verify (GADGETUP). */
if ( ((gpi->gpi_Mouse).X < g->LeftEdge) ||
((gpi->gpi_Mouse).X > g->LeftEdge + g->Width) ||
((gpi->gpi_Mouse).Y < g->TopEdge) ||
((gpi->gpi_Mouse).Y > g->TopEdge + g->Height) )
retval = GMR_NOREUSE | GMR_VERIFY;
else
retval = GMR_NOREUSE;

/* Since the gadget is going inactive, send a final */
/* notification to the ICA_TARGET. */
NotifyPulse(cl , o, 0L, inst->midX, (struct gpInput *)msg);
break;
case MENUDOWN: /* The user hit the menu button. Go inactive and let */
/* Intuition reuse the menu button event so Intuition can */
/* pop up the menu bar. */
retval = GMR_REUSE;

/* Since the gadget is going inactive, send a final */
/* notification to the ICA_TARGET. */
NotifyPulse(cl , o, 0L, inst->midX, (struct gpInput *)msg);
break;
default:
retval = GMR_MEACTIVE;
}

}
else if (ie->ie_Class == IECLASS_TIMER)
/* If the gadget gets a timer event, it sends an interim OM_NOTIFY */
NotifyPulse(cl, o, OPUF_INTERIM, inst->midX, gpi); /* to its superclass. */
}
break;

case GM_GOINACTIVE: /* Intuition said to go inactive. Clear the GFLG_SELECTED */
/* bit and render using unselected imagery. */
((struct Gadget *)o)->Flags &= ~GFLG_SELECTED;
RenderRKMBut(cl, (struct Gadget *)o, (struct gpRender *)msg);
break;
case OM_SET:/* Although this class doesn't have settable attributes, this gadget class */
/* does have scaleable imagery, so it needs to find out when its size and/or */
/* position has changed so it can erase itself, THEN scale, and rerender. */
if ( IUtility->FindTagItem(GA_Width, ((struct opSet *)msg)->ops_AttrList) ||
IUtility->FindTagItem(GA_Height, ((struct opSet *)msg)->ops_AttrList) ||
IUtility->FindTagItem(GA_Top, ((struct opSet *)msg)->ops_AttrList) ||
IUtility->FindTagItem(GA_Left, ((struct opSet *)msg)->ops_AttrList) )
{
struct RastPort *rp;
struct Gadget *g = (struct Gadget *)o;

WORD x,y,w,h;

x = g->LeftEdge;
y = g->TopEdge;
w = g->Width;
h = g->Height;

inst = (ButINST *)INST_DATA(cl, o);

retval = IIntuition->IDoSuperMethodA(cl, o, msg);

/* Get pointer to RastPort for gadget. */
if (rp = IIntuition->ObtainGIRPort( ((struct opSet *)msg)->ops_GInfo) )
{
UWORD *pens = ((struct opSet *)msg)->ops_GInfo->gi_DrInfo->dri_Pens;

IGraphics->SetAPen(rp, pens[BACKGROUNDPEN]);
IGraphics->SetDrMd(rp, JAM1); /* Erase the old gadget. */
IGraphics->RectFill(rp, x, y, x+w, y+h);

inst->midX = g->LeftEdge + ( (g->Width) / 2); /* Recalculate where the */
inst->midY = g->TopEdge + ( (g->Height) / 2); /* center of the gadget is. */

/* Rerender the gadget. */
IIntuition->IDoMethod(o, GM_RENDER, ((struct opSet *)msg)->ops_GInfo, rp, GREDRAW_REDRAW);
IIntuition->ReleaseGIRPort(rp);
}
}
else
retval = IIntuition->IDoSuperMethodA(cl, o, msg);
break;
default: /* rkmmodelclass does not recognize the methodID, let the superclass's */
/* dispatcher take a look at it. */
retval = IIntuition->IDoSuperMethodA(cl, o, msg);
break;
}
return(retval);
}

/*************************************************************************************************/
/************** Build an OM_NOTIFY message for RKMBUT_Pulse and send it to the superclass. *******/
/*************************************************************************************************/
void NotifyPulse(Class *cl, Object *o, ULONG flags, LONG mid, struct gpInput *gpi)
{
struct TagItem tt[3];

tt[0].ti_Tag = RKMBUT_Pulse;
tt[0].ti_Data = mid - ((gpi->gpi_Mouse).X + ((struct Gadget *)o)->LeftEdge);

tt[1].ti_Tag = GA_ID;
tt[1].ti_Data = ((struct Gadget *)o)->GadgetID;

tt[2].ti_Tag = TAG_END;

IIntuition->IDoSuperMethod(cl, o, OM_NOTIFY, tt, gpi->gpi_GInfo, flags);
}

/*************************************************************************************************/
/******************************* Erase and rerender the gadget. ******************************/
/*************************************************************************************************/
ULONG RenderRKMBut(Class *cl, struct Gadget *g, struct gpRender *msg)
{
struct ButINST *inst = (ButINST *)INST_DATA(cl, (Object *)g);
struct RastPort *rp;
ULONG retval = TRUE;
UWORD *pens = msg->gpr_GInfo->gi_DrInfo->dri_Pens;

if (msg->MethodID == GM_RENDER) /* If msg is truly a GM_RENDER message (not a gpInput that */
/* looks like a gpRender), use the rastport within it... */
rp = msg->gpr_RPort;
else /* ...Otherwise, get a rastport using ObtainGIRPort(). */
rp = IIntuition->ObtainGIRPort(msg->gpr_GInfo);

if (rp)
{
UWORD back, shine, shadow, w, h, x, y;

if (g->Flags & GFLG_SELECTED) /* If the gadget is selected, reverse the meanings of the */
{ /* pens. */
back = pens[FILLPEN];
shine = pens[SHADOWPEN];
shadow = pens[SHINEPEN];
}
else
{
back = pens[BACKGROUNDPEN];
shine = pens[SHINEPEN];
shadow = pens[SHADOWPEN];
}
IGraphics->SetDrMd(rp, JAM1);

IGraphics->SetAPen(rp, back); /* Erase the old gadget. */
IGraphics->RectFill(rp, g->LeftEdge,
g->TopEdge,
g->LeftEdge + g->Width,
g->TopEdge + g->Height);

IGraphics->SetAPen(rp, shadow); /* Draw shadow edge. */
IGraphics->Move(rp, g->LeftEdge + 1, g->TopEdge + g->Height);
IGraphics->Draw(rp, g->LeftEdge + g->Width, g->TopEdge + g->Height);
IGraphics->Draw(rp, g->LeftEdge + g->Width, g->TopEdge + 1);

w = g->Width / 4; /* Draw Arrows - Sorry, no frills imagery */
h = g->Height / 2;
x = g->LeftEdge + (w/2);
y = g->TopEdge + (h/2);

IGraphics->Move(rp, x, inst->midY);
IGraphics->Draw(rp, x + w, y);
IGraphics->Draw(rp, x + w, y + (g->Height) - h);
IGraphics->Draw(rp, x, inst->midY);

x = g->LeftEdge + (w/2) + g->Width / 2;

IGraphics->Move(rp, x + w, inst->midY);
IGraphics->Draw(rp, x, y);
IGraphics->Draw(rp, x, y + (g->Height) - h);
IGraphics->Draw(rp, x + w, inst->midY);

IGraphics->SetAPen(rp, shine); /* Draw shine edge. */
IGraphics->Move(rp, g->LeftEdge, g->TopEdge + g->Height - 1);
IGraphics->Draw(rp, g->LeftEdge, g->TopEdge);
IGraphics->Draw(rp, g->LeftEdge + g->Width - 1, g->TopEdge);

if (msg->MethodID != GM_RENDER) /* If we allocated a rastport, give it back. */
IIntuition->ReleaseGIRPort(rp);
}
else retval = FALSE;
return(retval);
}
</syntaxhighlight>

BOOPSI Gadgets

2024-09-10T09:04:27Z

Frédéric Khannouf: /* RKMButtonclass.c */ Little fixes and type castings to make g++ happy

=== Introduction ===

One of the major enhancements to Intuition is the implementation of customizable BOOPSI gadgets. BOOPSI gadgets are not limited by dependencies upon Intuition Image and Gadget structures. Unlike ordinary gadgets, which were handled exclusively by Intuition, BOOPSI gadgets handle their own rendering and their own user input.

Since BOOPSI gadgets draw themselves, there is almost no restriction on what they can look like. A BOOPSI gadget can use graphics.library RastPort drawing functions to draw vector-based imagery which the gadget can scale to any dimension. Instead of just a two-state Boolean gadget, a BOOPSI gadget can have any number of states, each of which has its own imagery. If a programmer wanted to he could even make a BOOPSI gadget that uses the animation system to render itself.

Because BOOPSI gadgets handle their own input, they see all the user's input, which the gadget is free to interpret. While the user has a BOOPSI gadget selected, the gadget can track mouse moves, process mouse and keyboard key presses, or watch the timer events.

The power of a BOOPSI gadget is not limited to its ability to handle its own rendering and user input. BOOPSI gadgets are also BOOPSI objects so the gain all the benefits BOOPSI provides. This means all BOOPSI gadgets inherit the methods and attributes from their superclasses. BOOPSI gadgets can use BOOPSI images to take care of rendering their imagery. A BOOPSI gadget could be a "composite" gadget that is composed of several BOOPSI gadgets, images, and models.

=== The BOOPSI Gadget Methods ===

Intuition drives a BOOPSI gadget by sending it BOOPSI messages. Intuition uses the following BOOPSI methods:

{| class="wikitable"
! Method !! Description
|-
| GM_DOMAIN || Obtain gadget sizing requirements.
|-
| GM_EXTENT || Inquire about rendering extent. (V51)
|-
| GM_GOACTIVE || This method asks a gadget if it wants to be the active gadget.
|-
| GM_GOINACTIVE || This method tells a gadget that it is no longer active.
|-
| GM_HANDLEINPUT || This method passes a gadget an input event.
|-
| GM_HELPTEST || Determine if gadget help was hit.
|-
| GM_HITTEST || This method asks a gadget whether it has been "hit" by a mouse click.
|-
| GM_LAYOUT || Calculate relative gadget coordinates.
|-
| GM_RENDER || This method tells the gadget to render itself.
|}

The formats of each of these BOOPSI messages differ, but they all have two things in common. Like all BOOPSI messages, each starts with their respective method ID. For each of these methods, the method ID field is followed by a pointer to a GadgetInfo structure (defined in <intuition/cghooks.h>). The GadgetInfo structure contains information about the display on which the gadget needs to render itself:

<syntaxhighlight>
struct GadgetInfo {
struct Screen *gi_Screen;
struct Window *gi_Window; /* null for screen gadgets */
struct Requester *gi_Requester; /* null if not GTYP_REQGADGET */

/* rendering information: don't use these without cloning/locking.
* Official way is to call ObtainGIRPort()
*/
struct RastPort *gi_RastPort;
struct Layer *gi_Layer;

/* copy of dimensions of screen/window/g00/req(/group)
* that gadget resides in. Left/Top of this box is
* offset from window mouse coordinates to gadget coordinates
* screen gadgets: 0,0 (from screen coords)
* window gadgets (no g00): 0,0
* GTYP_GZZGADGETs (borderlayer): 0,0
* GZZ innerlayer gadget: borderleft, bordertop
* Requester gadgets: reqleft, reqtop
*/
struct IBox gi_Domain;

/* these are the pens for the window or screen */
struct {
UBYTE DetailPen;
UBYTE BlockPen;
} gi_Pens;

/* the Detail and Block pens in gi_DrInfo->dri_Pens[] are
* for the screen. Use the above for window-sensitive colors.
*/
struct DrawInfo *gi_DrInfo;

/* reserved space: this structure is extensible
* anyway, but using these saves some recompilation
*/
ULONG gi_Reserved[6];
};
</syntaxhighlight>

All the fields in this structure are read only.

Although this structure contains a pointer to the gadget's RastPort structure, applications should not use it for rendering. Instead, use the intuition.library function ObtainGIRPort() to obtain a copy of the GadgetInfo's RastPort. When the gadget is finished with this RastPort, it should call ReleaseGIRPort() to relinquish the RastPort.

==== GM_DOMAIN ====

Intuition uses the GM_DOMAIN method to determine the basic sizing requirements of an object. The domain is most often used by layout gadgets to aid in distributing the gadgets within the layout via GM_LAYOUT. The GM_DOMAIN method uses the gpDomain structure (defined in <intuition/gadgetclass.h>) as its message:

<syntaxhighlight>
struct gpDomain
{
uint32 MethodID;
struct GadgetInfo *gpd_GInfo;
struct RastPort *gpd_RPort; /* RastPort to layout for */
int32 gpd_Which;
struct IBox gpd_Domain; /* Resulting domain */
struct TagItem *gpd_Attrs; /* Additional attributes */
};
</syntaxhighlight>

The gpd_Which field is used to determine which domain the caller is interested in: GDOMAIN_MINIMUM, GDOMAIN_NOMINAL or GDOMAIN_MAXIMUM. The object is expected to fill in the provided gpd_Domain with the width and height dimensions. The location coordinates are not used. The gpd_Attrs pointer, if not NULL, may contain additional tags which are defined on a per-class basis.

==== GM_EXTENT (V51) ====

The GM_EXTENT method is used to ask the gadget what pixels (at least) it will fully redraw when its GM_RENDER method is invoked in the same context. By "fully redraw" we mean changing the pixel's color in a way that is totally unrelated to its previous value -- so this doesn't apply to alpha-blended pixels for example.

Intuition uses that information for optimization purposes. During GUI refreshes, it will skip filling or erasing those pixels that the gadget would then completely re-render anyway. Supporting this method in your gadgets will help Intuition improve the smoothness of user interface refresh by preventing redundant graphic calls and minimizing "flicker" effects caused by background clearing especially during window resizes.

===== Simple Support =====

The easiest way to support GM_EXTENT is to make sure your gadget always fills every pixel within its dimensions and just return the relevant result value (GMR_FULLHBOX or GMR_FULLBBOX). In this case, you may safely ignore the actual message contents and the following text.

If the above solution is not feasible (for instance because the gadget has an irregular or not fully connected shape) then you should check the gpe_Region and gpe_RPort message fields: if any of them is non-NULL you may decide to employ a more detailed way to tell the caller exactly what pixels your GM_RENDER method does fill.

===== Region and RastPort Support =====

If gpe_Region is non-NULL you can compose in it your gadget's shape by using graphics.library's XxxxRectRegion() functions. Remember to look at the gpe_Action field to determine what function to use. For example, if gpe_Action is GEXTENT_ADD you should use OrRectRegion(). Note you must NOT pre-clear or alter the initial region's contents in any way other than to compose your own gadget's shape. Once finished composing your gadget's shape in the region, return GMR_CLIPDONE to let the caller know you updated the region's contents.

If gpe_RPort is non-NULL you can draw your gadget's shape into it just like you would do for a GM_RENDER message -- however, you're only allowed to use colors 0 or 1 because you're actually drawing into a single-bitplane mask. Again, check the gpe_Action field to find out whether you should actually set, clear or invert the pixels making up your gadget's shape in the mask. You are not allowed to alter any pixels other than those belonging to your gadget's shape nor to clear the mask's background before rendering. Once finished drawing your gadget's shape in the mask plane return GMR_MASKDONE to let the caller know you updated the mask's contents.

If both gpe_Region and gpe_RPort are non-NULL you may simply choose the method which is most suited for your purposes. You don't have to support both for the same message. If you do, however, you can let the caller know by ORing together the appropriate return values. The region solution is best suited for gadgets made up of a few rectangular parts whereas the mask method is better in the case of more complex gadget shapes.

===== Images =====

If all or part of your gadget's rendering is performed by some BOOPSI image you could also try asking the image for its extent information by way of an IM_EXTENT or IM_EXTENTFRAME message (see [[BOOPSI_Images|BOOPSI Images]]).

If for whatever reasons your GM_EXTENT method finds itself unable to support any of the described solutions it should return GMR_INVALID. This particular return value will tell Intuition not to clip away the gadget's shape at all. While this is usually slower and more prone to flickering it will still produce correct graphic results. This is the same fallback applied for any gadgets not recognizing the GM_EXTENT method.

===== Superclass Extent Handling =====

Since it is very important that a gadget's GM_RENDER and GM_EXTENT methods remain synchronized the default behavior of a gadget class should be to only handle GM_EXTENT if it is the "true class" of the object the method is invoked on and just return GMR_INVALID otherwise. This is because a subclass might override the behavior of GM_RENDER in such a way that your class' GM_EXTENT results are no longer correct.

If a gadget subclass needs and knows it's ok to let its superclass handle GM_EXTENT it must set the GPEF_ALLOWSUPER flag in gpe_Flags before calling IDoSuperMethodA() and clear it as soon as the call returns. If GPEF_ALLOWSUPER is set in gpe_Flags your gadget should accept and handle GM_EXTENT regardless of whether it is the true class or not.

{{Note|text=As of Intuition V51 the mask method is not yet implemented.}}

==== GM_GOACTIVE/GM_HANDLEINPUT ====

If a gadget returns GMR_GADGETHIT, Intuition will send it a GM_GOACTIVE message (defined in <intuition/gadgetclass.h>):

<syntaxhighlight>
struct gpInput /* Used by GM_GOACTIVE and GM_HANDLEINPUT */
{
ULONG MethodID;
struct GadgetInfo *gpi_GInfo;
struct InputEvent *gpi_IEvent; /* The input event that triggered this method
* (for GM_GOACTIVE, this can be NULL) */
LONG *gpi_Termination; /* For GADGETUP IntuiMessage.Code */
struct
{
WORD X; /* Mouse position relative to upper */
WORD Y; /* left corner of gadget (LeftEdge, TopEdge) */
} gpi_Mouse;
};
</syntaxhighlight>

The GM_GOACTIVE message gives a gadget the opportunity to become the active gadget. The active gadget is the gadget that is currently receiving user input. Under normal conditions, only one gadget can be the active gadget (it is possible to have more than one active gadget using a groupgclass object (See the [[BOOPSI_Class_Reference|BOOPSI Class Reference]] for more details).

While a gadget is active, Intuition sends it GM_HANDLEINPUT messages. Each GM_HANDLEINPUT message corresponds to a single InputEvent structure. These InputEvents can be keyboard presses, timer events, mouse moves, or mouse button presses. The message's gpi_IEvent field points to this InputEvent structure. It's up to the GM_HANDLEINPUT method to interpret the meaning of these events and update the visual state of the gadget as the user manipulates the gadget. For example, the GM_HANDLEINPUT method of a prop gadget has to track mouse events to see where the user has moved the prop gadget's knob and update the gadget's imagery to reflect the new position of the knob.

For the GM_GOACTIVE method, the gpi_IEvent field points to the struct InputEvent that triggered the GM_GOACTIVE message. Unlike the GM_HANDLEINPUT message, GM_GOACTIVE's gpi_IEvent can be NULL. If the GM_GOACTIVE message was triggered by a function like intuition.library's ActivateGadget() and not by a real InputEvent (like the user clicking the gadget), the gpi_IEvent field will be NULL.

For gadgets that only want to become active as a direct result of a mouse click, this difference is important. For example, the prop gadget becomes active only when the user clicks on its knob. Because the only way the user can control the prop gadget is via the mouse, it does not make sense for anything but the mouse to activate the gadget. On the other hand, a string gadget doesn't care how it is activated because, as soon as it's active, it gets user input from the keyboard rather than the mouse. Not all gadgets can become active. Some gadgets cannot become active because they have been temporarily disabled (their Gadget.Flags GFLG_DISABLED bit is set). Other gadgets will not become active because they don't need to process input. For example, a toggle gadget won't become active because it only needs to process one input event, the mouse click that toggles the gadget (which it gets from the GM_GOACTIVE message). If a toggle gadget gets a GM_GOACTIVE message and its gpi_IEvent field is not NULL, it will toggle its state and refuse to "go active".

The GM_GOACTIVE method has to take care of any visual state changes to a gadget that a GM_GOACTIVE message might trigger. For example, the toggle gadget in the previous paragraph has to take care of toggling its visual state from selected imagery to unselected imagery. If the gadget goes through a state change when it becomes the active gadget, (like when a string gadget positions its cursor) GM_GOACTIVE has to take care of this.

===== Return Values =====

The return values of both GM_GOACTIVE and GM_HANDLEINPUT tell Intuition whether or not the gadget wants to be active. A gadget's GM_GOACTIVE method returns GMR_MEACTIVE (defined in <intuition/gadgetclass.h>) if it wants to become the active gadget. A gadget's GM_HANDLEINPUT method returns GMR_MEACTIVE if it wants to remain the active gadget. If a gadget either does not want to become or remain the active gadget, it returns one of the "go inactive" return values:

; GMR_NOREUSE
: Tells Intuition to throw away the gpInput.gpi_IEvent InputEvent.

; GMR_REUSE
: Tells Intuition to process the gpInput.gpi_IEvent InputEvent.

; GMR_NEXTACTIVE
: Tells Intuition to throw away the gpInput.gpi_IEvent InputEvent and activate the next GFLG_TagCycle gadget.

; GMR_PREVACTIVE
: Tells Intuition to throw away the gpInput.gpi_IEvent InputEvent and activate the previous GFLG_TagCycle gadget.

GMR_NOREUSE tells Intuition that the gadget does not want to be active and to throw away the InputEvent that triggered the message. For example, an active prop gadget returns GMR_NOREUSE when the user lets go of the left mouse button (thus letting go of the prop gadget's knob).

For the GM_HANDLEINPUT method, a gadget can also return GMR_REUSE, which tells Intuition to reuse the InputEvent. For example, if the user clicks outside the active string gadget, that string gadget returns GMR_REUSE. Intuition can now process that mouse click, which can be over another gadget. Another case where a string gadget returns GMR_REUSE is when the user pushes the right mouse button (the menu button). The string gadget becomes inactive and the menu button InputEvent gets reused. Intuition sees this event and tries to pop up the menu bar.

For the GM_GOACTIVE method, a gadget must not return GMR_REUSE. If a gadget gets a GM_GOACTIVE message from Intuition and the message has an gpi_IEvent, the message was triggered by the user clicking on the gadget. In this case, Intuition knows that the user is trying to select the gadget. Intuition doesn't know if the gadget can be activated, but if it can be activated, the event that triggered the activation has just taken place. If the gadget cannot become active for any reason, it must not let Intuition reuse that InputEvent as the gadget has already taken care of the the event's purpose (clicking on the gadget). In essence, the user tried to activate the gadget and the gadget refused to become active.

The other two possible return values are GMR_NEXTACTIVE and GMR_PREVACTIVE. These tell Intuition that a gadget does not want to be active and that the InputEvent should be discarded. Intuition then looks for the next (GMR_NEXTACTIVE) or previous (GMR_PREVACTIVE) gadget that has its GFLG_TABCYCLE flag set in its Gadget.Activation field (see the gadgetclass GA_TabCycle attribute in the [[BOOPSI_Class_Reference|BOOPSI Class Reference]]).

For both GM_GOACTIVE and GM_HANDLEINPUT, the gadget can bitwise-OR any of these "go inactive" return values with GMR_VERIFY. The GMR_VERIFY flag tells Intuition to send a GADGETUP IntuiMessage to the gadget's window. If the gadget uses GMR_VERIFY, it has to supply a value for the IntuiMessage.Code field. It does this by passing a value in the gpInput.gpi_Termination field. This field points to a long word, the lower 16-bits of which Intuition copies into the Code field. The upper 16-bits are for future enhancements, so clear these bits.

==== GM_GOINACTIVE ====

After an active gadget deactivates, Intuition sends it a GM_GOINACTIVE message (defined in <intuition/gadgetclass.h>):

<syntaxhighlight>
struct gpGoInactive
{
ULONG MethodID; /* GM_GOINACTIVE */
struct GadgetInfo *gpgi_GInfo;
ULONG gpgi_Abort; /* gpgi_Abort=1 if gadget was aborted by Intuition */
/* and 0 if gadget went inactive at its own request. */
};
</syntaxhighlight>

The gpgi_Abort field contains either a 0 or 1. If 0, the gadget became inactive on its own power (because the GM_GOACTIVE or GM_HANDLEINPUT method returned something besides GMR_MEACTIVE). If gpgi_Abort is 1, Intuition aborted this active gadget. Some instances where Intuition aborts a gadget include: the user clicked in another window or screen, an application removed the active gadget with RemoveGList(), and an application called ActiveWindow() on a window other than the gadget's window.

==== GM_HELPTEST ====

This method uses the same message structure as GM_HITTEST, struct gpHitTest, and operates similarly to GM_HITTEST. While a window is in help mode, when the user positions the pointer within the bounding box of a BOOPSI gadget that supports gadget help, Intuition sends the gadget a GM_HELPTEST message. After an active gadget deactivates, Intuition sends it a GM_GOINACTIVE message.

<syntaxhighlight>
struct gpHitTest
{
uint32 MethodID; // GM_HELPTEST
struct GadgetInfo *gpht_GInfo;
struct
{
int16 X; // Is this point inside
int16 Y; // gadget?
} gpht_Mouse;
};
</syntaxhighlight>

Like the GM_HITTEST method, the GM_HELPTEST method asks a gadget if a point is within the gadget's bounds. Like the GM_HITTEST method, the GM_HELPTEST method allows a BOOPSI gadget to have a non-rectangular hit area (or in this case, a help area). If the point is within the gadget, the gadget uses one of two return codes. If the gadget returns a value of GMR_HELPHIT, Intuition places a value of 0xFFFF in the Code field of the IDCMP_GADGETHELP message. The gadget also has the option of using GMR_HELPCODE instead of GMR_HELPHIT. GMR_HELPCODE is a little peculiar as a return value. Although GMR_HELPCODE is 32 bits long, Intuition identifies GMR_HELPCODE using only its upper 16 bits. If the upper 16 bits of GM_HELPTEST's return value matches the upper 16 bits of GMR_HELPCODE, Intuition copies the lower word of the return value into the Code field of the IDCMP_GADGETHELP message. The BOOPSI gadget is free to set the return value's lower word to any 16-bit value.

If the point is not within the gadget's "help spot", the gadget returns GMR_NOHELPHIT. Intuition will then look under that gadget for more gadgets. If a gadget's dispatcher passes the GM_HELPTEST method on to the gadgetclass dispatcher, the gadgetclass dispatcher
will always return GMR_HELPHIT.

An application can put several windows in the same help group. This feature groups several windows so that as long as one of those windows is active, the application can receive IDCMP_GADGETHELP messages about all of those windows. For more information, See the HelpControl() Autodoc and the WA_HelpGroup section of the OpenWindow() Autodoc (both are in intuition.doc).

==== GM_HITTEST ====

When Intuition gets a left mouse button click in a window, one of the things it does is check through the window's list of gadgets to see if that click was inside the bounds of a gadget's Gadget structure (using the LeftEdge, TopEdge, Width, and Height fields). If it was (and that gadget is a BOOPSI gadget), Intuition sends that gadget a GM_HITTEST message (defined in <intuition/gadgetclass.h>):

<syntaxhighlight>
struct gpHitTest
{
uint32 MethodID; // GM_HITTEST
struct GadgetInfo *gpht_GInfo;
struct
{
int16 X; // Is this point inside
int16 Y; // gadget?
} gpht_Mouse;
};
</syntaxhighlight>

This message contains the coordinates of the mouse click. These coordinates are relative to the upper-left of the gadget (LeftEdge, TopEdge).

Because Intuition can only tell if the user clicked inside gadget's "bounding box", Intuition only knows that the click was close to the gadget. Intuition uses the GM_HITTEST to ask the gadget if the click was really inside the gadget. The gadget returns GMR_GADGETHIT (defined in <intuition/gadgetclass.h>) to tell Intuition that the user hit it, otherwise it returns zero. This method allows a gadget to be any shape or pattern, rather than just rectangular.

==== GM_LAYOUT ====

Intuition uses the GM_LAYOUT method to tell a GREL BOOPSI gadget that its window's dimensions have changed. The GM_LAYOUT method uses the gpLayout structure (defined in <intuition/gadgetclass.h>) as its message:

<syntaxhighlight>
struct gpLayout
{
uint32 MethodID;
struct GadgetInfo *gpl_GInfo;
uint32 gpl_Initial; /* This field is non-zero if this method was invoked
* during AddGList() or OpenWindow(). zero if this
* method was invoked during window resizing.
*/
};
</syntaxhighlight>

For GREL gadgets, Intuition sends a GM_LAYOUT message just after erasing the gadget's bounding box. Intuition does not touch the values of the gadget's bounding box or hit box, it lets the gadget handle recalculating these values. The gadget can lay itself out based on the new window (or requester) dimensions found in the GadgetInfo structure passed in the GM_LAYOUT message (gpl_GInfo from the gpLayout structure). Intuition also adds the old and new bounding box of the gadget to the window's damaged regions so that the gadget will appear is its new position. The gadget must not perform any rendering inside the GM_LAYOUT method. Intuition will send a GM_RENDER message to the gadget when its time to redraw the gadget in its new position.

There are two cases where Intuition sends a GM_LAYOUT message:
# When the gadget's window is resized
# When Intuition adds the gadget to a window

For most GREL BOOPSI gadgets, Intuition expects the values in the LeftEdge, TopEdge, Width, and Height fields to follow the existing convention for regular GREL gadgets. Each of these fields has a flag in the Gadget.Flags field (GFLG_RELRIGHT, GFLG_RELBOTTOM, GFLG_RELWIDTH, and GFLG_RELHEIGHT, respectively). If that field's flag is set, Intuition expects the value in that field to be relative to either the window border or the window dimensions. For example, if GFLG_RELRIGHT is set, Intuition expects the value in the gadget's LeftEdge field to be relative to the right window border.

There is a special kind of GREL BOOPSI gadget called a custom relativity gadget. For this type of gadget, Intuition expects the values in the LeftEdge, TopEdge, Width, and Height fields to be absolute measurements, just like the values Intuition expects in these fields for non-GREL gadgets.

Setting the GFLG_RELSPECIAL bit in the Gadget.Flags field marks the gadget as a custom relativity gadget. The best way to set this bit is by setting the GA_RelSpecial attribute to TRUE when creating the gadget.

==== GM_RENDER ====

Every time Intuition feels it is necessary to redraw a BOOPSI gadget, it sends a gadget a GM_RENDER message. The GM_RENDER message (defined in <intuition/gadgetclass.h>) tells a gadget to render itself:

<syntaxhighlight>
struct gpRender
{
uint32 MethodID; /* GM_RENDER */
struct GadgetInfo *gpr_GInfo;
struct RastPort *gpr_RPort; /* all ready for use */
int32 gpr_Redraw; /* might be a "highlight pass" */
};
</syntaxhighlight>

Some events that cause Intuition to send a GM_RENDER are: an application passed the gadget to OpenWindow(), the user moved or resized a gadget's window, or an application explicitly asked Intuition to refresh some gadgets.

The GM_RENDER message contains a pointer to the gadget's RastPort so the GM_RENDER method does not have to extract it from the gpr_GInfo GadgetInfo structure using ObtainGIRPort()). The gadget renders itself according to how much imagery it needs to replace. The gpr_Redraw field contains one of three values:

{| class="wikitable"
| GREDRAW_REDRAW
| Redraw the entire gadget.
|-
| GREDRAW_UPDATE
| The user has manipulated the gadget, causing a change to its imagery. Update only that part of the gadget's imagery that is effected by the user manipulating the gadget (for example, the knob and scrolling field of the prop gadget).
|-
| GREDRAW_TOGGLE
| If this gadget supports it, toggle to or from the highlighting imagery.
|}

Intuition is not the only entity that calls this method. The gadget's other methods may call this method to render the gadget when it goes through state changes. For example, as a prop gadget is following the mouse from the gadget's GM_HANDLEINPUT method, the gadget could send itself GM_RENDER messages, telling itself to update its imagery according to where the mouse has moved.

The DoRender() method should always be used by class implementers to invoke a GM_RENDER method on a gadget object. Applications use the RefreshGList() function which will invoke GM_RENDER for the caller in the proper context.

=== The Active Gadget ===

While a gadget is active, Intuition sends it a GM_HANDLEINPUT message for every timer pulse, mouse move, mouse click, and key press that takes place. A timer event pulse arrives about every tenth of a second. Mouse move events can arrive at a much higher rate than the timer pulses. Without even considering the keyboard, a gadget can get a lot of GM_HANDLEINPUT messages in a short amount of time. Because the active gadget has to handle a large volume of GM_HANDLEINPUT messages, the overhead of this method should be kept to a minimum.

Because the gadget will always receive a GM_GOACTIVE message before it is active and a GM_GOINACTIVE message after it is no longer active, the gadget can use these methods to allocate, initialize, and deallocate temporary resources it needs for the GM_HANDLEINPUT method. This can significantly reduce the overhead of GM_HANDLEINPUT because it eliminates the need to allocate, initialize, and deallocate resources for every GM_HANDLEINPUT message.

Note that the RastPort from ObtainGIRPort() is not cachable using this method. If the GM_HANDLEINPUT method needs to use a RastPort, it has to obtain and release the RastPort for every GM_HANDLEINPUT message using ObtainGIRPort() and ReleaseGIRPort().

=== RKMButtonclass.c ===

The following example is a sample BOOPSI gadget, RKMButClass.c.

While the user has the RKMButton selected, the gadget sends an OM_UPDATE message to its ICA_TARGET for every timer event the button sees.

The gadget sends notification about its RKMBUT_Pulse attribute, which is the horizontal distance in screen pixels the mouse is from the center of the button. 
The gadget takes care of rendering all of its imagery (as opposed to using a BOOPSI image to do it). 
The gadget's imagery is scalable to any dimensions and can be set (using SetGadgetAttrs()) while the gadget is in place. 

One possible use for such a gadget is as buttons for a prop gadget.

If the user has the prop gadget's RKMButton selected, while the mouse is to the left of the button's center, the knob on the prop gadget moves left. 
While the mouse is to the right of the button's center, the knob on the prop gadget moves right. 
The speed at which the knob moves is proportional to the horizontal distance from the mouse to the active RKMButton. 

<syntaxhighlight lang="cpp">
/* RKMButClass.c - Example BOOPSI gadget */

#include <exec/types.h>
#include <intuition/intuition.h>
#include <intuition/classes.h>
#include <intuition/classusr.h>
#include <intuition/imageclass.h>
#include <intuition/gadgetclass.h>
#include <intuition/cghooks.h>
#include <intuition/icclass.h>
#include <utility/tagitem.h>
#include <utility/hooks.h>

#include <proto/exec.h>
#include <proto/intuition.h>
#include <proto/graphics.h>
#include <proto/utility.h>

#include <graphics/gfxmacros.h>

CONST_STRPTR vers = "$VER: TestBut 50.1";

/***********************************************************/
/**************** Class specifics ****************/
/***********************************************************/
#define RKMBUT_Pulse (TAG_USER + 1)

struct ButINST
{
LONG midX, midY; /* Coordinates of middle of gadget */
};

/* ButINST has one flag: */
#define ERASE_ONLY 0x00000001 /* Tells rendering routine to */
/* only erase the gadget, not */
/* rerender a new one. This */
/* lets the gadget erase it- */
/* self before it rescales. */

/* The functions in this module */
Class *initRKMButGadClass(void);
BOOL freeRKMButGadClass(Class *);
ULONG dispatchRKMButGad(Class *, Object *, Msg);
void NotifyPulse(Class *, Object *, ULONG, LONG, struct gpInput *);
ULONG RenderRKMBut(Class *, struct Gadget *, struct gpRender *);
void MainLoop(ULONG, ULONG);

/*************************************************************************************************/
/* The main() function connects an RKMButClass object to a BOOPSI integer gadget, which displays */
/* the RKMButClass gadget's RKMBUT_Pulse value. The code scales and move the gadget while it is */
/* in place. */
/*************************************************************************************************/

struct TagItem pulse2int[] =
{
{RKMBUT_Pulse, STRINGA_LongVal},
{TAG_END,}
};

#define INTWIDTH 40
#define INTHEIGHT 20

struct IntuitionIFace *IIntuition;
struct GraphicsIFace *IGraphics;
struct Window *w;
Class *rkmbutcl;
struct Gadget *integer, *but;
struct IntuiMessage *msg;

int main(void)
{
struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
struct Library *GfxBase = IExec->OpenLibrary("graphics.library", 50);

IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);
IGraphics = (struct GraphicsIFace*)IExec->GetInterface(GfxBase, "main", 1, NULL);

if (IIntuition != NULL && IGraphics != NULL)
{
if (w = IIntuition->OpenWindowTags(NULL,
WA_Flags, WFLG_DEPTHGADGET | WFLG_DRAGBAR |
WFLG_CLOSEGADGET | WFLG_SIZEGADGET,
WA_IDCMP, IDCMP_CLOSEWINDOW,
WA_Width, 640,
WA_Height, 200,
TAG_END))
{
IIntuition->WindowLimits(w, 450, 200, 640, 200);

if (rkmbutcl = initRKMButGadClass())
{
if (integer = (struct Gadget *)IIntuition->NewObject(NULL,
"strgclass",
GA_ID, 1L,
GA_Top, (w->BorderTop) + 5L,
GA_Left, (w->BorderLeft) + 5L,
GA_Width, INTWIDTH,
GA_Height, INTHEIGHT,
STRINGA_LongVal, 0L,
STRINGA_MaxChars, 5L,
TAG_END))
{
if (but = (struct Gadget *)IIntuition->NewObject(rkmbutcl,
NULL,
GA_ID, 2L,
GA_Top, (w->BorderTop) + 5L,
GA_Left, integer->LeftEdge +
integer->Width + 5L,
GA_Width, 40L,
GA_Height, INTHEIGHT,
GA_Previous, integer,
ICA_MAP, pulse2int,
ICA_TARGET, integer,
TAG_END))
{
IIntuition->AddGList(w, integer, -1, -1, NULL);
IIntuition->RefreshGList(integer, w, NULL, -1);

IIntuition->SetWindowTitles(w,
"<-- Click to resize gadget Height",
NULL);
MainLoop(TAG_END, 0L);

IIntuition->SetWindowTitles(w,
"<-- Click to resize gadget Width",
NULL);
MainLoop(GA_Height, 100L);

IIntuition->SetWindowTitles(w,
"<-- Click to resize gadget Y position",
NULL);
MainLoop(GA_Width, 100L);

IIntuition->SetWindowTitles(w,
"<-- Click to resize gadget X position",
NULL);
MainLoop(GA_Top, but->TopEdge + 20);

IIntuition->SetWindowTitles(w,
"<-- Click to quit", NULL);
MainLoop(GA_Left, but->LeftEdge + 20);

IIntuition->RemoveGList(w, integer, -1);
IIntuition->DisposeObject((Object *)but);
}
IIntuition->DisposeObject((Object *)integer);
}
freeRKMButGadClass(rkmbutcl);
}
IIntuition->CloseWindow(w);
}
}

IExec->DropInterface((struct Interface*)IGraphics);
IExec->DropInterface((struct Interface*)IIntuition);
IExec->CloseLibrary(GfxBase);
IExec->CloseLibrary(IntuitionBase);

return 0;
}

void MainLoop(ULONG attr, ULONG value)
{
ULONG done = FALSE;

IIntuition->SetGadgetAttrs(but, w, NULL, attr, value, TAG_END);

while (done == FALSE)
{
IExec->WaitPort((struct MsgPort *)w->UserPort);
while (msg = (struct IntuiMessage *)
IExec->GetMsg((struct MsgPort *)w->UserPort))
{
if (msg->Class == IDCMP_CLOSEWINDOW)
{
done = TRUE;
}
IExec->ReplyMsg((Message *)msg);
}
}
}

/***********************************************************/
/** Make the class and set up the dispatcher's hook **/
/***********************************************************/
Class *initRKMButGadClass(void)
{
Class *cl = NULL;
extern ULONG HookEntry(); /* defined in amiga.lib */

if ( cl = IIntuition->MakeClass( NULL,
"gadgetclass", NULL,
sizeof ( struct ButINST ),
0 ))
{
/* initialize the cl_Dispatcher Hook */
cl->cl_Dispatcher.h_Entry = (HOOKFUNC)dispatchRKMButGad;
}
return ( cl );
}

/***********************************************************/
/****************** Free the class ****************/
/***********************************************************/
BOOL freeRKMButGadClass(Class *cl)
{
return IIntuition->FreeClass(cl);
}

/***********************************************************/
/********** The RKMBut class dispatcher *********/
/***********************************************************/
ULONG dispatchRKMButGad(Class *cl, Object *o, Msg msg)
{
struct ButINST *inst;
ULONG retval = FALSE;
Object *object;

switch (msg->MethodID)
{
case OM_NEW: /* First, pass up to superclass */
if (object = (Object *)IIntuition->IDoSuperMethodA(cl, o, msg))
{
struct Gadget *g = (struct Gadget *)object;

/* Initial local instance data */
inst = (ButINST *)INST_DATA(cl, object);
inst->midX = g->LeftEdge + ( (g->Width) / 2);
inst->midY = g->TopEdge + ( (g->Height) / 2);

retval = (ULONG)object;
}
break;
case GM_HITTEST:
/* Since this is a rectangular gadget this */
/* method always returns GMR_GADGETHIT. */
retval = GMR_GADGETHIT;
break;
case GM_GOACTIVE:
inst = (ButINST*)INST_DATA(cl, o);

/* Only become active if the GM_GOACTIVE */
/* was triggered by direct user input. */
if (((struct gpInput *)msg)->gpi_IEvent)
{
/* This gadget is now active, change */
/* visual state to selected and render. */
((struct Gadget *)o)->Flags |= GFLG_SELECTED;
RenderRKMBut(cl, (struct Gadget *)o, (struct gpRender *)msg);
retval = GMR_MEACTIVE;
}
else /* The GM_GOACTIVE was not */
/* triggered by direct user input. */
retval = GMR_NOREUSE;
break;
case GM_RENDER:
retval = RenderRKMBut(cl, (struct Gadget *)o, (struct gpRender *)msg);
break;
case GM_HANDLEINPUT: /* While it is active, this gadget sends its superclass an */
/* OM_NOTIFY pulse for every IECLASS_TIMER event that goes by */
/* (about one every 10th of a second). Any object that is */
/* connected to this gadget will get A LOT of OM_UPDATE messages. */
{
struct Gadget *g = (struct Gadget *)o;
struct gpInput *gpi = (struct gpInput *)msg;
struct InputEvent *ie = gpi->gpi_IEvent;

inst = (ButINST*)INST_DATA(cl, o);

retval = GMR_MEACTIVE;

if (ie->ie_Class == IECLASS_RAWMOUSE)
{
switch (ie->ie_Code)
{
case SELECTUP: /* The user let go of the gadget so return GMR_NOREUSE */
/* to deactivate and to tell Intuition not to reuse */
/* this Input Event as we have already processed it. */

/*If the user let go of the gadget while the mouse was */
/*over it, mask GMR_VERIFY into the return value so */
/*Intuition will send a Release Verify (GADGETUP). */
if ( ((gpi->gpi_Mouse).X < g->LeftEdge) ||
((gpi->gpi_Mouse).X > g->LeftEdge + g->Width) ||
((gpi->gpi_Mouse).Y < g->TopEdge) ||
((gpi->gpi_Mouse).Y > g->TopEdge + g->Height) )
retval = GMR_NOREUSE | GMR_VERIFY;
else
retval = GMR_NOREUSE;

/* Since the gadget is going inactive, send a final */
/* notification to the ICA_TARGET. */
NotifyPulse(cl , o, 0L, inst->midX, (struct gpInput *)msg);
break;
case MENUDOWN: /* The user hit the menu button. Go inactive and let */
/* Intuition reuse the menu button event so Intuition can */
/* pop up the menu bar. */
retval = GMR_REUSE;

/* Since the gadget is going inactive, send a final */
/* notification to the ICA_TARGET. */
NotifyPulse(cl , o, 0L, inst->midX, (struct gpInput *)msg);
break;
default:
retval = GMR_MEACTIVE;
}

}
else if (ie->ie_Class == IECLASS_TIMER)
/* If the gadget gets a timer event, it sends an interim OM_NOTIFY */
NotifyPulse(cl, o, OPUF_INTERIM, inst->midX, gpi); /* to its superclass. */
}
break;

case GM_GOINACTIVE: /* Intuition said to go inactive. Clear the GFLG_SELECTED */
/* bit and render using unselected imagery. */
((struct Gadget *)o)->Flags &= ~GFLG_SELECTED;
RenderRKMBut(cl, (struct Gadget *)o, (struct gpRender *)msg);
break;
case OM_SET:/* Although this class doesn't have settable attributes, this gadget class */
/* does have scaleable imagery, so it needs to find out when its size and/or */
/* position has changed so it can erase itself, THEN scale, and rerender. */
if ( IUtility->FindTagItem(GA_Width, ((struct opSet *)msg)->ops_AttrList) ||
IUtility->FindTagItem(GA_Height, ((struct opSet *)msg)->ops_AttrList) ||
IUtility->FindTagItem(GA_Top, ((struct opSet *)msg)->ops_AttrList) ||
IUtility->FindTagItem(GA_Left, ((struct opSet *)msg)->ops_AttrList) )
{
struct RastPort *rp;
struct Gadget *g = (struct Gadget *)o;

WORD x,y,w,h;

x = g->LeftEdge;
y = g->TopEdge;
w = g->Width;
h = g->Height;

inst = (ButINST *)INST_DATA(cl, o);

retval = IIntuition->IDoSuperMethodA(cl, o, msg);

/* Get pointer to RastPort for gadget. */
if (rp = IIntuition->ObtainGIRPort( ((struct opSet *)msg)->ops_GInfo) )
{
UWORD *pens = ((struct opSet *)msg)->ops_GInfo->gi_DrInfo->dri_Pens;

IGraphics->SetAPen(rp, pens[BACKGROUNDPEN]);
IGraphics->SetDrMd(rp, JAM1); /* Erase the old gadget. */
IGraphics->RectFill(rp, x, y, x+w, y+h);

inst->midX = g->LeftEdge + ( (g->Width) / 2); /* Recalculate where the */
inst->midY = g->TopEdge + ( (g->Height) / 2); /* center of the gadget is. */

/* Rerender the gadget. */
IIntuition->IDoMethod(o, GM_RENDER, ((struct opSet *)msg)->ops_GInfo, rp, GREDRAW_REDRAW);
IIntuition->ReleaseGIRPort(rp);
}
}
else
retval = IIntuition->IDoSuperMethodA(cl, o, msg);
break;
default: /* rkmmodelclass does not recognize the methodID, let the superclass's */
/* dispatcher take a look at it. */
retval = IIntuition->IDoSuperMethodA(cl, o, msg);
break;
}
return(retval);
}

/*************************************************************************************************/
/************** Build an OM_NOTIFY message for RKMBUT_Pulse and send it to the superclass. *******/
/*************************************************************************************************/
void NotifyPulse(Class *cl, Object *o, ULONG flags, LONG mid, struct gpInput *gpi)
{
struct TagItem tt[3];

tt[0].ti_Tag = RKMBUT_Pulse;
tt[0].ti_Data = mid - ((gpi->gpi_Mouse).X + ((struct Gadget *)o)->LeftEdge);

tt[1].ti_Tag = GA_ID;
tt[1].ti_Data = ((struct Gadget *)o)->GadgetID;

tt[2].ti_Tag = TAG_END;

IIntuition->IDoSuperMethod(cl, o, OM_NOTIFY, tt, gpi->gpi_GInfo, flags);
}

/*************************************************************************************************/
/******************************* Erase and rerender the gadget. ******************************/
/*************************************************************************************************/
ULONG RenderRKMBut(Class *cl, struct Gadget *g, struct gpRender *msg)
{
struct ButINST *inst = (ButINST *)INST_DATA(cl, (Object *)g);
struct RastPort *rp;
ULONG retval = TRUE;
UWORD *pens = msg->gpr_GInfo->gi_DrInfo->dri_Pens;

if (msg->MethodID == GM_RENDER) /* If msg is truly a GM_RENDER message (not a gpInput that */
/* looks like a gpRender), use the rastport within it... */
rp = msg->gpr_RPort;
else /* ...Otherwise, get a rastport using ObtainGIRPort(). */
rp = IIntuition->ObtainGIRPort(msg->gpr_GInfo);

if (rp)
{
UWORD back, shine, shadow, w, h, x, y;

if (g->Flags & GFLG_SELECTED) /* If the gadget is selected, reverse the meanings of the */
{ /* pens. */
back = pens[FILLPEN];
shine = pens[SHADOWPEN];
shadow = pens[SHINEPEN];
}
else
{
back = pens[BACKGROUNDPEN];
shine = pens[SHINEPEN];
shadow = pens[SHADOWPEN];
}
IGraphics->SetDrMd(rp, JAM1);

IGraphics->SetAPen(rp, back); /* Erase the old gadget. */
IGraphics->RectFill(rp, g->LeftEdge,
g->TopEdge,
g->LeftEdge + g->Width,
g->TopEdge + g->Height);

IGraphics->SetAPen(rp, shadow); /* Draw shadow edge. */
IGraphics->Move(rp, g->LeftEdge + 1, g->TopEdge + g->Height);
IGraphics->Draw(rp, g->LeftEdge + g->Width, g->TopEdge + g->Height);
IGraphics->Draw(rp, g->LeftEdge + g->Width, g->TopEdge + 1);

w = g->Width / 4; /* Draw Arrows - Sorry, no frills imagery */
h = g->Height / 2;
x = g->LeftEdge + (w/2);
y = g->TopEdge + (h/2);

IGraphics->Move(rp, x, inst->midY);
IGraphics->Draw(rp, x + w, y);
IGraphics->Draw(rp, x + w, y + (g->Height) - h);
IGraphics->Draw(rp, x, inst->midY);

x = g->LeftEdge + (w/2) + g->Width / 2;

IGraphics->Move(rp, x + w, inst->midY);
IGraphics->Draw(rp, x, y);
IGraphics->Draw(rp, x, y + (g->Height) - h);
IGraphics->Draw(rp, x + w, inst->midY);

IGraphics->SetAPen(rp, shine); /* Draw shine edge. */
IGraphics->Move(rp, g->LeftEdge, g->TopEdge + g->Height - 1);
IGraphics->Draw(rp, g->LeftEdge, g->TopEdge);
IGraphics->Draw(rp, g->LeftEdge + g->Width - 1, g->TopEdge);

if (msg->MethodID != GM_RENDER) /* If we allocated a rastport, give it back. */
IIntuition->ReleaseGIRPort(rp);
}
else retval = FALSE;
return(retval);
}
</syntaxhighlight>

Workbench Library

2024-02-19T10:00:51Z

Frédéric Khannouf: /* An AppIcon Example */ Typo fix

== Workbench Library ==

Workbench is the graphic user interface to the Amiga file system that uses symbols called icons to represent disks, directories and files. This article shows how to use workbench.library.

Workbench is both a system program and a screen. Normally it is the first thing the user sees when the machine is booted providing a friendly operating environment for launching applications and performing other important system activities like navigating through the Amiga's hierarchical filing system.

All application programs should be compatible with Workbench. There are only two things you need to know to do this: how to make icons for your application, data files and directories; and how to get arguments if your application is launched from Workbench.

== The Info File ==

The iconic representation of Amiga filing system objects is implemented through ''.info'' files. In general, for each file, disk or directory that is visible in the Workbench environment, there is an associated ''.info'' file which contains the icon imagery and other information needed by Workbench.

Icons are associated with a particular file or directory by name. For example, the icon for a file named ''myapp'' would be stored in a ''.info'' file named ''myapp.info'' in the same directory.

To make your application program accessible (and visible) in the Workbench environment, you need only supply a ''.info'' file with the appropriate name and type. The are four main types of icons (and ''.info'' files) used to represent Amiga filing system objects.

{| class="wikitable"
|+ Basic Workbench Icon Types
! Workbench Icon Type
! Image
! Filing System Object
! Result When Icon Is Activated
|-
| Disk || [[File:LibDiskIcon.png]] || The root level directory || Window opens showing files and subdirectories
|-
| Drawer || [[File:LibDrawerIcon.png]] || A subdirectory || Window opens showing files and subdirectories
|-
| Tool || [[File:LibToolIcon.png]] || An executable file || Application runs (i.e., an application)
|-
| Project || [[File:LibProjectIcon.png]] || A data file || Typically, the application that created the data file runs and the data file is automatically loaded into it.
|}

Icons can be created with the IconEdit program (in the Tools directory of the Extras disk), or by copying an existing ''.info'' file of the correct type. Icons can also be created under program control with PutDiskObject(). See [[Icon Library]] for a discussion of the icon library functions.

'''The icon type can be set and the icon imagery edited with the IconEdit program.''' For an executable file the icon type must be set to tool. For a data file the icon type must be set to project. Create icons for your application disk and directories too. For a directory, the icon is stored in a ''.info'' file at the same level where the directory name appears (not in the directory itself). The icon type should be set to drawer. The icon for a disk should always be stored in a file named ''disk.info'' at the root level directory of the disk. The icon type should be set to disk.

== Workbench Environment ==

On the Amiga there are at least two ways to start a program running:

* By activating a tool or project icon in Workbench (an icon is activated by pointing to it with the mouse and double-clicking the mouse select button.)
* By typing the name of an executable file at the Shell (also known as the CLI or Command Line Interface)

In the Workbench environment, a program is run as a separate process. A process is simply a task with additional information needed to use DOS library.

By default, a Workbench program does not have a window to which its output will go. Therefore, ''stdin'', ''stdout'' and ''stderr'' do not point to legal file handles. This means you cannot use ''stdio'' functions such as printf() if your program is started from Workbench unless you first set up a ''stdio'' window.

Some compilers have options or defaults to provide a ''stdio'' window for programs started from Workbench. Applications can use an auto console window for ''stdio'' when started from Workbench by opening "CON:0/0/640/200/auto/close/wait" as a file. An auto console window will only open if ''stdio'' input or output occurs. This can also be handled in the startup code module that comes with your compiler.

=== Argument Passing in Workbench ===

Applications started from Workbench receive arguments in the form of a WBStartup structure. This is similar to obtaining arguments from a command line interface through argc and argv. The WBStartup message contains an argument count and a pointer to a list of file and directory names.

==== One Argument ====

A program started by activating its tool icon gets one argument in the WBStartup message: the name of the tool itself.

==== Two Arguments ====

All project icons (data files) have a ''default tool'' field associated with them that tells Workbench which application tool to run in order to operate on the data that the icon represents. When the user activates a project icon, Workbench runs the application specified in the default tool field passing it two arguments in the WBStartup message: the name of the tool and the project icon that the user activated.

==== Multiple Arguments ====

With ''extended select'', the user can activate many icons at once. (Extended select means the user holds down the Shift key while clicking the mouse select button once on each icon in a group, double-clicking on the last icon.) If one of the icons in a group activated with extended select is an application tool, Workbench runs that application passing it the name of all the other icons in the group. This allows the user to start an application with multiple project files as arguments. If none of the icons in a group activated with extended select is a tool icon, then Workbench looks in the default tool field of each icon in the order they were selected and runs the first tool it finds.

=== WBStartup Message ===

When Workbench loads and starts a program, its sends the program a WBStartup message containing the arguments as summarized above. Normally, the startup code supplied with your compiler will place a pointer to WBStartup in argv for you, set argc to zero and call your program.

The WBStartup message, whose structure is outlined in <workbench/startup.h>, has the following structure elements:

<syntaxhighlight>
struct WBStartup
{
struct Message sm_Message; /* a standard message structure */
struct MsgPort * sm_Process; /* the process descriptor for you */
BPTR sm_Segment; /* a descriptor for your code */
LONG sm_NumArgs; /* the number of elements in ArgList */
char * sm_ToolWindow; /* reserved for future use */
struct WBArg * sm_ArgList; /* the arguments themselves */
};
</syntaxhighlight>

The fields of the WBStartup structure are used as follows.

; sm_Message
: A standard Exec message. The reply port is set to the Workbench.

; sm_Process
: The process descriptor for the tool (as returned by CreateProcess())

; sm_Segment
: The loaded code for the tool (returned by LoadSeg())

; sm_NumArgs
: The number of arguments in sm_ArgList

; sm_ToolWindow
: Reserved (not currently passed in startup message)

; sm_ArgList
: This is the argument list itself. It is a pointer to an array of WBArg structures with sm_NumArgs elements.

Workbench arguments are passed as an array of WBArg structures in the sm_ArgList field of WBStartup. The first WBArg in the list is always the tool itself. If multiple icons have been selected when a tool is activated, the selected icons are passed to the tool as additional WBArgs. If the tool was derived from a default tool, the project will be the second WBArg. If extended select was used, arguments other than the tool are passed in the order of selection; the first icon selected will be first (after the tool), and so on.

Each argument is a struct WBArg and has two parts: wa_Name and wa_Lock.

<syntaxhighlight>
struct WBArg
{
BPTR wa_Lock; /* a lock descriptor */
BYTE * wa_Name; /* a string relative to that lock */
};
</syntaxhighlight>

The wa_Name element is the name of an AmigaDOS filing system object. The wa_Name field of the first WBArg is always the name of your program and the wa_Lock field is an AmigaDOS Lock on the directory where your program is stored.

If your program was started by activating a project icon, then you get a second WBarg with the wa_Name field containing the file name of the project and the wa_Lock containing an AmigaDOS Lock on the directory where the project file is stored.

If your program was started through extended select, then you get one WBArg for each icon in the selected group in the order they were selected. The wa_Name field contains the file name corresponding to each icon unless the icon is for a directory, disk, or the Trashcan in which case the wa_Name is set to NULL. The wa_Lock field contains an AmigaDOS Lock on the directory where the file is stored. (For disk or drawer icons the wa_Lock is a lock on the directory represented by the icon. Or, wa_Lock may be NULL if the icon type does not support locks.)

{{Note|title=Workbench Locks Belong to Workbench|text=You must never call UnLock() on a wa_Lock. These locks belong to Workbench, and Workbench will UnLock() them when the WBStartup message is replied by your startup code. You must also never UnLock() your program's initial current directory lock (i.e., the lock returned by an initial CurrentDir() call). The classic symptom caused by unlocking Workbench locks is a system hang after your program exits, even though the same program exits with no problems when started from the Shell.}}

You should save the lock returned from an initial CurrentDir(), and CurrentDir() back to it before exiting. In the Workbench environment, depending on your startup code, the current directory will generally be set to one of the wa_Locks. By using CurrentDir(wa_Lock) and then referencing wa_Name, you can find, read, and modify the files that have been passed to your program as WBArgs.

=== Example of Parsing Workbench Arguments ===

The following example will display all WBArgs if started from Workbench, and all Shell arguments if started from the Shell.

<syntaxhighlight>
/* prargs.c
**
** PrArgs.c - This program prints all Workbench or Shell (CLI) arguments.
*/
#include <exec/types.h>
#include <workbench/startup.h>
#include <proto/dos.h>

int main(int argc, char **argv)
{
struct WBStartup *argmsg;
struct WBArg *wb_arg;
int32 ktr;
BPTR olddir;
BPTR outFile;

/* argc is zero when run from the Workbench,
** positive when run from the CLI.
*/
if (argc == 0)
{
/* AmigaDOS has a special facility that allows a window */
/* with a console and a file handle to be easily created. */
/* CON: windows allow you to use fprintf() with no hassle */
if (ZERO != (outFile = IDOS->Open("CON:0/0/640/200/PrArgs", MODE_NEWFILE)))
{
/* In AmigaOS, argv is a pointer to the WBStartup message
** when argc is zero. (run under the Workbench.)
*/
argmsg = (struct WBStartup *)argv ;
wb_arg = argmsg->sm_ArgList ; /* head of the arg list */

IDOS->FPrintf(outFile, "Run from the workbench, %ld args.\n",
argmsg->sm_NumArgs);

for (ktr = 0; ktr < argmsg->sm_NumArgs; ktr++, wb_arg++)
{
if (ZERO != wb_arg->wa_Lock)
{
/* locks supported, change to the proper directory */
olddir = IDOS->CurrentDir(wb_arg->wa_Lock) ;

/* process the file.
** If you have done the CurrentDir() above, then you can
** access the file by its name. Otherwise, you have to
** examine the lock to get a complete path to the file.
*/
IDOS->FPrintf(outFile, "\tArg %2.2ld (w/ lock): '%s'.\n",
ktr, wb_arg->wa_Name);

/* change back to the original directory when done.
** be sure to change back before you exit.
*/
IDOS->CurrentDir(olddir) ;
}
else
{
/* something that does not support locks */
IDOS->FPrintf(outFile, "\tArg %2.2ld (no lock): '%s'.\n",
ktr, wb_arg->wa_Name);
}
}
/* wait before closing down */
IDOS->Delay(500L);
IDOS->Close(outFile);
}
}
else
{
/* using 'tinymain' from lattice c.
** define a place to send the output (originating CLI window = "*")
** Note - if you open "CONSOLE:" and your program is RUN, the user will not
** be able to close the CLI window until you close the "CONSOLE:" file.
*/
if (ZERO != (outFile = IDOS->Open("CONSOLE:", MODE_NEWFILE)))
{
IDOS->FPrintf(outFile, "Run from the CLI, %d args.\n", argc);

for ( ktr = 0; ktr < argc; ktr++)
{
/* print an arg, and its number */
IDOS->FPrintf(outFile, "\tArg %2.2ld: '%s'.\n", ktr, argv[ktr]);
}
IDOS->Close(outFile);
}
}

return 0;
}
</syntaxhighlight>

== The Workbench Library ==

Workbench arguments are sent to an application when it is started. There are also special facilities that allow an application that is already running to get additional arguments. These special facilities are known as AppWindow, AppIcon and AppMenuItem.

An AppWindow is a special kind of window that allows the user to drag icons into it. Applications that set up an AppWindow will receive a message from Workbench whenever the user moves an icon into the AppWindow. The message contains the name of the file or directory that the icon represents.

An AppIcon is similar to an AppWindow. It is a special type of icon that allows the user to drag other icons on top of it. Like AppWindows, an application that sets up an AppIcon will receive a message from Workbench whenever the user moves another icon on top of the AppIcon. The message contains the name of the file or directory that the moved icon represents.

An AppMenuItem allows an application to add a custom menu item to the usual set of menu choices supported by Workbench. An application that sets up an AppMenuItem will receive a message from Workbench whenever the user picks that item from the Workbench menus.

When an application receives the messages described above, the message will include struct WBArg *am_ArgList containing the names (wa_Name) and directory locks (wa_Lock) of all selected icons that were passed as arguments by the user. This am_ArgList has the same format as the sm_ArgList of a WBStartup message.

=== The AppMessage Structure ===

When Workbench notifies an application of AppWindow, AppIcon, or AppMenuItem activity, it sends an AppMessage to the application's message port (from <workbench/workbench.h>):

<syntaxhighlight>
#define AM_VERSION 1

struct AppMessage {
struct Message am_Message; /* standard message structure */
UWORD am_Type; /* message type */
ULONG am_UserData; /* application specific */
ULONG am_ID; /* application definable ID */
LONG am_NumArgs; /* # of elements in arglist */
struct WBArg *am_ArgList; /* the arguments themselves */
UWORD am_Version; /* will be AM_VERSION */
UWORD am_Class; /* message class */
WORD am_MouseX; /* mouse x position of event */
WORD am_MouseY; /* mouse y position of event */
ULONG am_Seconds; /* current system clock time */
ULONG am_Micros; /* current system clock time */
ULONG am_Reserved[8];
};
</syntaxhighlight>

The AppMessage's am_Type field tells the application which type of AppObject the message is about. The field will be:
* AMTYPE_APPWINDOW if the message is about an AppWindow,
* AMTYPE_APPICON if the message is about an AppIcon, or
* AMTYPE_APPMENUITEM if the message is about an AppMenuItem.

When an application creates an AppObject, it can assign the AppObject application specific data (most likely a pointer) and an ID. Workbench will pass an AppObject's data and ID back to the application when it sends an AppMessage about the AppObject. The AppMessage's am_UserData and am_ID fields hold the user data and the ID.

The am_NumArgs field tells how many icons were involved in the user's AppObject action. For an AppWindow or AppIcon, am_NumArgs is the number of icons the user dropped on the AppWindow or AppIcon. For an AppMenuItem, am_NumArgs represents the number of icons that were selected when the user selected this AppMenuItem. If no icons were selected during an AppMenuItem event or the user double-clicked on an AppIcon, am_NumArgs will be zero. Workbench does not send AppMessages if the user double-clicks an AppWindow.

The am_ArgList field is a pointer to a list of WBArgs (from <workbench/startup.h>) corresponding to each icon dropped (or selected). If there were no icons dropped or selected, this field will be NULL.

For future expansion possibilities, the AppMessage structure has a version number. The version number is #defined as AM_VERSION in <workbench/workbench.h>.

The am_MouseX and am_MouseY fields apply only to AppWindows and contain the coordinates of the mouse pointer when the user dropped the icon(s). These coordinates are relative to the AppWindow's upper left corner.

The am_Seconds and am_Micros fields represent the time that the event took place.

Any remaining fields are undefined at present and should be set to NULL.

=== Workbench Library Functions ===

AppWindows, AppIcons and AppMenuItems extend the user's ability to perform operations with the Workbench iconic interface. They all provide graphical methods for passing arguments to a running application. In order to manage AppWindows, AppIcons and AppMenuItems, the Amiga OS includes these Workbench library functions:

<syntaxhighlight>
struct AppIcon *AddAppIconA( ULONG, ULONG, char *, struct MsgPort *, struct FileLock *,
struct DiskObject *, struct *TagItem );
struct AppMenuItem *AddAppMenuItemA( ULONG, ULONG, char *, struct MsgPort *, struct *TagItem);
struct AppWindow *AddAppWindowA( ULONG, ULONG, struct Window *, struct MsgPort *, struct *TagItem);

BOOL RemoveAppIcon(struct AppIcon *);
BOOL RemoveAppMenuItem(struct AppMenuItem *);
BOOL RemoveAppWindow(struct AppWindow *);
</syntaxhighlight>

The functions AddAppMenuItemA(), AddAppWindowA() and AddAppIconA() have alternate entry points using the same function name without the trailing A. The alternate functions accept any TagItem arguments on the stack instead of from an array. See the listings below for examples.

=== An AppIcon Example ===

The example listed here shows how to create an AppIcon and obtain arguments from Workbench when the user drops other icons on top of it. The AppIcon will appear as a disk icon named "TestAppIcon" on the Workbench screen. (All AppIcons appear on the Workbench screen or window.)

For convenience, this example code uses GetDefDiskObject() to create the icon imagery for the AppIcon. Applications should never do this. Use your own custom imagery for AppIcons instead.

<syntaxhighlight>
/* appicon.c
/* Works from the Shell (CLI) only */

#include <exec/types.h> /* Need this for the Amiga variable types */
#include <workbench/workbench.h> /* This has DiskObject and AppIcon structs */
#include <workbench/startup.h> /* This has WBStartup and WBArg structs */
#include <exec/libraries.h> /* Need this to check library versions */

#include <proto/icon.h> /* Icon (DiskObject) function prototypes */
#include <proto/exec.h> /* Exec message, port and library functions*/
#include <proto/workbench.h> /* AppIcon function protos */

struct Library *IconBase;
struct Library *WorkbenchBase;
struct IconIFace *IIcon;
struct WorkbenchIFace *IWorkbench;

int main(int argc, char **argv)
{
struct DiskObject *dobj=NULL;
struct MsgPort *myport=NULL;
struct AppIcon *appicon=NULL;
struct AppMessage *appmsg=NULL;

LONG dropcount=0L;
ULONG x;
BOOL success=0L;

IconBase = IExec->OpenLibrary("icon.library", 50);
WorkbenchBase = IExec->OpenLibrary("workbench.library", 50);

IIcon = (struct IconIFace*)IExec->GetInterface(IconBase, "main", 1, NULL);
IWorkbench = (struct WorkbenchIFace*)IExec->GetInterface(WorkbenchBase, "main", 1, NULL);

/* Get the the right version of the Icon Library, initialize IconBase */
if(IIcon != NULL && IWorkbench != NULL)
{
/* This is the easy way to get some icon imagery */
/* Real applications should use custom imagery */
dobj = IIcon->GetDefDiskObject(WBDISK);
if(dobj != 0)
{
/* The type must be set to NULL for a WBAPPICON */
dobj->do_Type = NULL;

myport = IExec->AllocSysObjectTags(ASOT_PORT, NULL);
if(myport)
{
/* Put the AppIcon up on the Workbench window */
appicon = IWorkbench->AddAppIconA(0L,0L,"TestAppIcon",myport,NULL,dobj,NULL);
if(appicon)
{
/* For the sake of this example, we allow the AppIcon */
/* to be activated only five times. */
IDOS->Printf("Drop files on the Workbench AppIcon\n");
IDOS->Printf("Example exits after 5 drops\n");

while(dropcount<5)
{
/* Here's the main event loop where we wait for */
/* messages to show up from the AppIcon */
IExec->WaitPort(myport);

/* Might be more than one message at the port... */
while(appmsg=(struct AppMessage *)IExec->GetMsg(myport))
{
if(appmsg->am_NumArgs==0L)
{
/* If NumArgs is 0 the AppIcon was activated directly */
IDOS->Printf("User activated the AppIcon.\n");
IDOS->Printf("A Help window for the user would be good here\n");
}
else if(appmsg->am_NumArgs>0L)
{
/* If NumArgs is >0 the AppIcon was activated by */
/* having one or more icons dropped on top of it */
IDOS->Printf("User dropped %ld icons on the AppIcon\n",
appmsg->am_NumArgs);
for(x=0;x<appmsg->am_NumArgs;x++)
{
IDOS->Printf("#%ld name='%s'\n",x+1,appmsg->am_ArgList[x].wa_Name);
}
}
/* Let Workbench know we're done with the message */
IExec->ReplyMsg((struct Message *)appmsg);
}
dropcount++;
}
success = IWorkbench->RemoveAppIcon(appicon);
}
/* Clear away any messages that arrived at the last moment */
while(appmsg = (struct AppMessage *)IExec->GetMsg(myport))
IExec->ReplyMsg((struct Message *)appmsg);
IExec->FreeSysObject(ASOT_PORT, myport);
}
IIcon->FreeDiskObject(dobj);
}

IExec->DropInterface((struct Interface*)IWorkbench);
IExec->DropInterface((struct Interface*)IIcon);

IExec->CloseLibrary(WorkbenchBase);
IExec->CloseLibrary(IconBase);

return 0;
}
</syntaxhighlight>

=== An AppMenuItem Example ===

This example shows how to create an AppMenuItem. The example adds a menu item named "Browse Files" to the Workbench Tools menu. (All AppMenuItems appear in the Workbench Tools menu.) When the menu item is activated, the example program receives a message from Workbench and then attempts to start up an instance of the More program. (The More program is in the Utilities directory of the Workbench volume.)

The example starts up the More program as a separate, asynchronous process using the SystemTags() function. When the AppMenuItem has been activated five times, the program exits after freeing any system resources it has used.

<syntaxhighlight>
/* appmenuitem.c
/* Works from the Shell (CLI) only */

#include <exec/types.h> /* Need this for the Amiga variable types */
#include <workbench/workbench.h> /* This has DiskObject and AppIcon structs */
#include <workbench/startup.h> /* This has WBStartup and WBArg structs */
#include <exec/libraries.h>
#include <dos/dostags.h>

#include <proto/dos.h>
#include <proto/exec.h> /* Exec message, port and library functions*/
#include <proto/workbench.h> /* AppMenuItem function protos */

struct Library *WorkbenchBase;
struct WorkbenchIFace *IWorkbench;

int main(int argc, char **argv)
{
struct MsgPort *myport=NULL;
struct AppMenuItem *appitem=NULL;
struct AppMessage *appmsg=NULL;
LONG result, x, count=0L;
BOOL success=0L;
BPTR file;

WorkbenchBase = IExec->OpenLibrary("workbench.library", 50);
IWorkbench = (struct WorkbenchIFace*)IExec->GetInterface(WorkbenchBase, "main", 1, NULL);

if (IWorkbench != NULL)
{
if(myport = IExec->AllocSysObjectTags(ASOT_PORT, NULL))
{
/* Add our own AppMenuItem to the Workbench Tools Menu */
appitem = IWorkbench->AddAppMenuItemA(0L, /* Our ID# for item */
(ULONG)"SYS:Utilities/More", /* Our UserData */
"Browse Files", /* MenuItem Text */
myport,NULL); /* MsgPort, no tags */
if(appitem)
{
IDOS->Printf("Select Workbench Tools demo menuitem 'Browse Files'\n");

/* For this example, we allow the AppMenuItem to be selected */
/* only once, then we remove it and exit */
IExec->WaitPort(myport);
while((appmsg = (struct AppMessage *)IExec->GetMsg(myport)) && (count<1))
{
/* Handle messages from the AppMenuItem - we have only one */
/* item so we don't have to check its appmsg->am_ID number. */
/* We'll System() the command string that we passed as */
/* userdata when we added the menu item. */
/* We find our userdata pointer in appmsg->am_UserData */

IDOS->Printf("User picked AppMenuItem with %ld icons selected\n",
appmsg->am_NumArgs);
for(x=0;x<appmsg->am_NumArgs;x++)
IDOS->Printf(" #%ld name='%s'\n",x+1,appmsg->am_ArgList[x].wa_Name);

count++;
if( file=Open("CON:0/40/640/150/AppMenu Example/auto/close/wait",
MODE_OLDFILE) ) /* for any stdio output */
{
result=IDOS->SystemTags((UBYTE *)appmsg->am_UserData,SYS_Input,file,
SYS_Output,NULL,
SYS_Asynch,TRUE,
TAG_END);
/* If Asynch System() itself fails, we must close file */
if(result == -1) IDOS->Close(file);
}
IExec->ReplyMsg((struct Message *)appmsg);
}
success = IWorkbench->RemoveAppMenuItem(appitem);
}

/* Clear away any messages that arrived at the last moment */
/* and let Workbench know we're done with the messages */
while(appmsg=(struct AppMessage *)IExec->GetMsg(myport))
{
IExec->ReplyMsg((struct Message *)appmsg);
}
IExec->FreeSysObject(ASOT_PORT, myport);
}

IExec->DropInterface((struct Interface*)IWorkbench);
IExec->CloseLibrary(WorkbenchBase);

return 0;
}
</syntaxhighlight>

=== An AppWindow Example ===

This example shows how to create an AppWindow and obtain arguments from Workbench when the user drops an icon into it. The AppWindow will appear on the Workbench screen with the name "AppWindow" and will run until the window's close gadget is selected. If any icons are dropped into the AppWindow, the program prints their arguments in the Shell window.

<syntaxhighlight>
/* appwindow.c */
/* Works from the Shell (CLI) only */

#include <exec/types.h> /* Need this for the Amiga variable types */
#include <workbench/workbench.h> /* This has DiskObject and AppWindow */
#include <workbench/startup.h> /* This has WBStartup and WBArg structs */
#include <exec/libraries.h> /* Need this to check library versions */

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>
#include <proto/workbench.h>

struct Library *IntuitionBase;
struct Library *WorkbenchBase;
struct IntuitionIFace *IIntuition;
struct WorkbenchIFace *IWorkbench;

int main(int argc, char **argv)
{
struct MsgPort *awport;
struct Window *win;
struct AppWindow *appwin;
struct IntuiMessage *imsg;
struct AppMessage *amsg;
struct WBArg *argptr;

ULONG winsig, appwinsig, signals, id = 1, userdata = 0;
BOOL done = FALSE;
int i;

IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
WorkbenchBase = IExec->OpenLibrary("workbench.library", 50);

IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);
IWorkbench = (struct WorkbenchIFace*)IExec->GetInterface(WorkbenchBase, "main", 1, NULL);

if (IIntuition != NULL)
{
if (IWorkbench != NULL)
{
if (awport = IExec->AllocSysObjectTags(ASOT_PORT, NULL))
{
if (win = IIntuition->OpenWindowTags(NULL,
WA_Width, 200, WA_Height, 50,
WA_IDCMP, CLOSEWINDOW,
WA_Flags, WINDOWCLOSE | WINDOWDRAG,
WA_Title, "AppWindow",
TAG_END))
{
if (appwin = IWorkbench->AddAppWindow(id, userdata, win, awport, NULL))
{
IDOS->Printf("AppWindow added... Drag files into AppWindow\n");
winsig = 1L << win->UserPort->mp_SigBit;
appwinsig = 1L << awport->mp_SigBit;

while (! done)
{
/* Wait for IDCMP messages and AppMessages */
signals = IExec->Wait( winsig | appwinsig );

if(signals & winsig) /* Got an IDCMP message */
{
while (imsg = (struct IntuiMessage *) IExec->GetMsg(win->UserPort))
{
if (imsg->Class = CLOSEWINDOW) done = TRUE;
IExec->ReplyMsg((struct Message *) imsg);
}
}
if(signals & appwinsig) /* Got an AppMessage */
{
while (amsg = (struct AppMessage *) IExec->GetMsg(awport))
{
IDOS->Printf("AppMsg: Type=%ld, ID=%ld, NumArgs=%ld\n",
amsg->am_Type, amsg->am_ID, amsg->am_NumArgs);
argptr = amsg->am_ArgList;
for (i = 0; i < amsg->am_NumArgs; i++)
{
IDOS->Printf(" arg(%ld): Name='%s', Lock=%lx\n",
i, argptr->wa_Name, argptr->wa_Lock);
argptr++;
}
IExec->ReplyMsg((struct Message *) amsg);
}
}
} /* done */
IWorkbench->RemoveAppWindow(appwin);
}
IIntuition->CloseWindow(win);
}
/* Make sure there are no more outstanding messages */
while(amsg = (struct AppMessage *)IExec->GetMsg(awport))
IExec->ReplyMsg((struct Message *)amsg);
IExec->FreeSysObject(ASOT_PORT, awport);
}
}
}

IExec->DropInterface((struct Interface*)IIntuition);
IExec->DropInterface((struct Interface*)IWorkbench);
IExec->CloseLibrary(IntuitionBase);
IExec->CloseLibrary(WorkbenchBase);

return 0;
}
</syntaxhighlight>

== Workbench and the Startup Code Module ==

Standard startup code handles the detail work of interfacing with the arguments and environment of Workbench and the Shell (or CLI). This section describes the behavior of standard startup modules such as the ones supplied with newlib and clib2.

The environment for a program started from Workbench is quite different from the environment for a program started from the Shell. The Shell does not create a new process for a program; it jumps to the program's code and the program shares the process with the Shell. Programs run under the Shell have access to all the Shell's environment, including the ability to modify that environment. (Programs run from the Shell should be careful to restore all values that existed on startup.) Workbench starts a program as a new DOS process, explicitly passing the execution environment to the program.

=== Workbench Startup ===

When the user activates a project or tool icon, the program is run as a separate process asynchronous to Workbench. This allows the user to take full advantage of the multitasking features of the Amiga. A process is simply a task with additional information needed to use DOS library.

When Workbench loads and starts a program, it sends the program a WBStartup message containing the arguments as described earlier. The WBStartup also contains a pointer to the new Process structure which describes the execution environment of the program. The WBStartup message is posted to the message port of the program's Process structure.

The Process message port is for the exclusive use of DOS, so this message must be removed from the port before using any DOS library functions. Normally this is handled by the startup code module that comes with your compiler so you don't have to worry about this unless you are writing your own startup code.

Standard startup code modules also set up SysBase, the pointer to the Exec master library, and open the DOS library setting up DOSBase. That is why Exec and AmigaDOS functions can be called by C applications without first opening a library; the startup code that applications are linked with handles this. Some special startups may also set up NIL: input and output streams, or may open a ''stdio'' window so that the Workbench applications can use stdio functions such as printf().

The startup code can tell if it is running in the Workbench environment because the pr_CLI field of the Process structure will contain NULL. In that case the startup code removes the WBStartup message from the Process message port with GetMsg() before using any functions in the DOS library.

{{Note|title=Do Not Use the Process Message Port for Anything Else|text=The message port in a Process structure is for the exclusive use of the DOS library.}}

Standard startup code will pass the WBStartup message pointer in argv and 0 (zero) in argc if the program is started from Workbench. The startup code calls the application code that it is linked with as a function. When the application code exits back to the startup code, the startup code closes and frees all opens and allocations it made. It will then Forbid(), and ReplyMsg() the WBStartup message, notifying Workbench that the application Process may be terminated and its code unloaded from memory.

{{Note|title=Avoid the DOS Exit() function|text=The DOS Exit() function does ''not'' return an application to the startup code that called it. If you wish to exit your application, use the exit function provided by your startup code (usually lower-case exit(), or _exit for assembler), passing it a valid DOS return code as listed in the include file <libraries/dos.h>.}}

=== Shell Startup ===

When a program is started from the Shell (or a Shell script), standard startup modules will parse the command line into an array of pointers to individual argument strings placing them in argv, and an argument count in argc.

If a program is started from the Shell, argc will always equal at least one and the first element in argv will always be a pointer to the command name. Other command line arguments are stored in turn. For example, if the command line was:

<pre>
df0:myprogram "my file1" file2 ;this is a comment
</pre>

then argc will be 3, argv[0] will be "df0:myprogram", argv[1] will be "my file1", and argv[2] will be "file2". Correct startup code will strip spaces between arguments and trailing spaces from the last argument and will also properly deal with quoted arguments with embedded spaces.

As with Workbench, standard startup code for the Shell sets up SysBase, the pointer to the Exec master library, and opens the DOS library setting up DOSBase. C applications that are linked with standard startup code can call an Exec or AmigaDOS functions without opening the library first.

The startup code also fills in the ''stdio'' file handles (_stdin, _stdout, etc.) for the application. Finally argv and argc, are pushed onto the stack and the application is called. When the application returns or exits back to the startup code, the startup code closes and frees all opens and allocations it has made for the application, and then returns to the system with the whatever value the program exited with.

Link your applications only with standard, tested startup code of some type such as the module supplied with your compiler. Startup code provides your programs with correct, consistent handling of Shell command line and Workbench arguments and will perform some initializations and cleanups which would otherwise need to be handled by your own code. Very small startups can be used for programs that do not require command line arguments.

A few words of warning for those of you who do not use standard startup code:

* If you are started as a Workbench process, you ''must'' GetMsg() the WBStartup message before using any functions in the DOS library.
* You ''must'' turn off task switching (with Forbid()) before replying the WBStartup message from Workbench. This will prevent Workbench from unloading your code before you can exit properly.
* If you do your own command line parsing, you ''must'' provide the user with consistent and correct handling of command line arguments.

== Function Reference ==

The following are brief descriptions of the functions in workbench.library. See SDK for details on each function call.

{| class="wikitable"
|+Workbench Library Functions
|-
! Function
! Description
|-
| AddAppIcon()
| Add an AppIcon to Workbench
|-
| AddAppMenuItem()
| Add an AppMenuItem to the Workbench Tools menu
|-
| AddAppWindow()
| Add an AppWindow to Workbench
|-
| RemoveAppIcon()
| Remove an AppIcon to Workbench
|-
| RemoveAppMenuItem()
| Remove an AppMenuItem to the Workbench Tools menu
|-
| RemoveAppWindow()
| Remove an AppWindow to Workbench
|}

How to open and use the exec debug interface

2024-01-29T13:20:11Z

Frédéric Khannouf: Added missing backslash

[[Category:Debug]]
== Author ==

Alfkil Wennermark 
Copyright (c) 2010 Alfkil Wennermark 
Used by permission.

== Tutorial ==

Next step in my small series concerns itself with how to open and use the "secret" (but very useful) debug interface. Thanks to Steven Solie and Thomas Frieden.

Probably the best way to trap exceptions from within your code is to use the debug interface, that is "hidden" inside exec.library. The main problem with this interface is, that it is not very well documented. My main source of documentation on this issue is the amigaos-nat.c file from Thomas Friedens [[GDB_for_Beginners|GDB]] sources. These can be found inside [https://sourceforge.net/projects/adtools/ the adtools project on sourceforge.net].

The following code just plainly opens the interface, attaches a debug hook to itself, causes an exception and tells you what has happened. Normally you wouldn't attach the hook to your own process. Rather you would open whatever code you want to debug with fx. LoadSeg(), run it with CreateNewProc() (or some other way) and attach the debug hook to it. To keep things simple, though, this code just attaches the hook to itself.

<syntaxhighlight>
/* debugtrap.cExample of use of the exec debug interface
by Alfkil Wennermark 2010

Thanks to Steven Solie, Thomas Frieden and others

This code is partially copied from Thomas' GDB source
*/

#include <proto/exec.h>
#include <proto/dos.h>

#include <exec/types.h>
#include <exec/interrupts.h>
#include <exec/tasks.h>

#include <dos/dos.h>

#include <stdio.h>

struct DebugIFace *IDebug = 0;

struct KernelDebugMessage
{
uint32 type;
union
{
struct ExceptionContext *context;
struct Library *library;
} message;
};

static ULONG amigaos_debug_callback(struct Hook *, struct Task *, struct KernelDebugMessage *);

struct Hook debug_hook;
struct Task *amiga_task;

BPTR exec_seglist;
ULONG debug_data = 1234;

void init()
{
IDebug = (struct DebugIFace *)IExec->GetInterface((struct Library *)SysBase, "debug", 1, 0);
if (!IDebug)
{
printf("Can't get DEBUG access\n");
exit(RETURN_FAIL);
}

debug_hook.h_Entry = (ULONG (*)())amigaos_debug_callback;
debug_hook.h_Data =(APTR)&debug_data;

/* NB: Ideally we would start up another task, that
we want to debug, and attach ourselves to that
task using the debug hook, but for simplicity
we just use our own task here */
amiga_task = IExec->FindTask(NULL);
IDebug->AddDebugHook(amiga_task, &debug_hook);
}

void end()
{
IDebug->AddDebugHook(amiga_task, 0);

if (IDebug)IExec->DropInterface((struct Interface *)IDebug);
IDebug = NULL;
}

ULONG
amigaos_debug_callback(struct Hook *hook, struct Task *currentTask,
struct KernelDebugMessage *dbgmsg)
{
struct ExecIFace *IExec = (struct ExecIFace *)((struct ExecBase *)SysBase)->MainInterface;

uint32 *data = (uint32 *)hook->h_Data;

/* these are the 4 types of debug msgs: */
switch (dbgmsg->type)
{
case DBHMT_REMTASK:
*data = 9;
break;

case DBHMT_EXCEPTION:
*data = 11;
break;

case DBHMT_OPENLIB:
*data = 13;
break;

case DBHMT_CLOSELIB:
*data = 15;
break;

default:
*data = 0;
break;
}
/* returning 1 will suspend the task ! */
return 0;
}

int main()
{
init();

/* Cause an exception on purpose: */
uint32 *beef = 0;
*beef = 0L;

printf("We received a");
switch (debug_data)
{
case 9:
printf(" REMTASK");
break;
case 11:
printf("n EXCEPTION");
break;
case 13:
printf("n OPENLIB");
break;
case 15:
printf(" CLOSELIB");
break;

default:
printf("n unknown");
break;
}
printf(" signal!n");

end();

return RETURN_OK;
}
</syntaxhighlight>

Exec Signals

2023-09-13T07:15:54Z

Frédéric Khannouf: /* SIGBREAKB_CTRL_E */ Typo fixes

== Exec Signals ==

[[Exec Tasks|Tasks]] often need to coordinate with other concurrent system activities (like other [[Exec Tasks|tasks]] and [[Exec Interrupts|interrupts]]). This coordination is handled by Exec through the synchronized exchange of specific event indicators called ''signals''.

This is the primary mechanism responsible for all inter-task communication and synchronization on the Amiga. This signal mechanism operates at a low level and is designed for high performance. Signals are used extensively by the Exec message system as a way to indicate the arrival of an inter-task message. The message system is described in more detail in [[Exec Messages and Ports]].

{{Note|title=Not for Beginners.|text=This section concentrates on details about signals that most applications do not need to understand for general Amiga programming. For a general overview of signals, see [[Introduction to Exec]].}}

== The Signal System ==

The signal system is designed to support independent simultaneous events, so several signals can occur at the same time. Each task has 32 independent signals, 16 of which are pre-allocated for use by the operating system. The signals in use by a particular task are represented as bits in a 32-bit field in its Task structure (<exec/tasks.h>). Two other 32-bit fields in the Task structure indicate which signals the task is waiting for, and which signals have been received.

Signals are ''task relative''. A task can only allocate its own signals, and may only wait on its own signals. In addition, a task may assign its own significance to a particular signal. Signals are not broadcast to all tasks; they are directed only to individual tasks. A signal has meaning to the task that defined it and to those tasks that have been informed of its meaning.

For example, signal bit 12 may indicate a timeout event to one task, but to another task it may indicate a message arrival event. You can never wait on a signal that you did not directly or indirectly allocate yourself, and any other task that wishes to signal you must use a signal that ''you'' allocated.

=== Signal Allocation ===

As mentioned above, a task assigns its own meaning to a particular signal. Because certain system libraries may occasionally require the use of a signal, there is a convention for signal allocation. It is unwise ever to make assumptions about which signals are actually in use.

Before a signal can be used, it must be allocated with the AllocSignal() function. When a signal is no longer needed, it should be freed for reuse with FreeSignal().

<syntaxhighlight>
BYTE AllocSignal( LONG signalNum );
VOID FreeSignal( LONG signalNum );
</syntaxhighlight>

AllocSignal() marks a signal as being in use and prevents the accidental use of the same signal for more than one event. You may ask for either a specific signal number, or more commonly, you would pass -1 to request the next available signal. The state of the newly allocated signal is cleared (ready for use). Generally it is best to let the system assign you the next free signal. Of the 32 available signals, the lower 16 are reserved for system use (see [[#Reserved_System_Signals|Reserved System Signals]]). This leaves the upper 16 signals free for application programs to allocate. Other subsystems that you may call depend on AllocSignal().

The following example asks for the next free signal to be allocated for its use:

<syntaxhighlight>
if (-1 == (signal = IExec->AllocSignal(-1)))
IDOS->Printf("no signal bits available\n");
else
{
IDOS->Printf("allocated signal number %ld\n", signal);
/* Other code could go here */
IExec->FreeSignal(signal)
}
</syntaxhighlight>

The value returned by AllocSignal() is a signal bit number. This value cannot be used directly in calls to signal-related functions without first being converted to a mask:

<syntaxhighlight>
uint32 mask = 1UL << signal;
or
uint32 mask = (uint32)1 << signal;
</syntaxhighlight>

It is important to realize that signal bit allocation is relevant ''only'' to the running task. You ''cannot'' allocate a signal from another task. Note that functions which create a signal MsgPort will allocate a signal from the task that calls the function. Such functions include OpenWindow() and AllocSysObject(). For this reason, only the creating task may Wait() (directly or indirectly) on the MsgPort's signal. Functions which call Wait() include DoIO(), WaitIO() and WaitPort().

=== Waiting for a Signal ===

Signals are most often used to wake up a task upon the occurrence of some external event. Applications call the Exec Wait() function, directly or indirectly, in order to enter a wait state until some external event triggers a signal which awakens the task.

Though signals are usually not used to interrupt an executing task, they can be used this way. Task ''exceptions'', described in [[Exec_Interrupts|Exec Interrupts]], allow signals to act as a task-local interrupt.

The Wait() function specifies the set of signals that will wake up the task and then puts the task to sleep (into the waiting state).

<syntaxhighlight>
ULONG Wait( ULONG signalSet );
</syntaxhighlight>

Any one signal or any combination of signals from this set are sufficient to awaken the task. Wait() returns a mask indicating which signals satisfied the Wait() call. Note that when signals are used in conjunction with a message port, a set signal bit does not necessarily mean that there is a message at the message port.

See [[Exec_Messages_and_Ports|Exec Messages and Ports]] for details about proper handling of messages.

Because tasks (and interrupts) normally execute asynchronously, it is often possible to receive a particular signal before a task actually Wait()s for it. In such cases the Wait() will be immediately satisfied, and the task will not be put to sleep.

The Wait() function implicitly clears those signal bits that satisfied the wait condition. This effectively resets those signals for reuse. However, keep in mind that a task might get more signals while it is still processing the previous signal. If the same signal is received multiple times and the signal bit is not cleared between them, some signals will go unnoticed.

Be aware that using Wait() will break a Forbid() or Disable() state. Wait() cannot be used in supervisor mode or within interrupts.

A task may Wait() for a combination of signal bits and will wake up when any of the signals occur. Wait() returns a signal mask specifying which signal or signals were received. Usually the program must check the returned mask for each signal it was waiting on and take the appropriate action for each that occurred. The order in which these bits are checked is often important.

Here is a hypothetical example of a process that is using the console and timer devices, and is waiting for a message from either device and a possible break character issued by the user:

<syntaxhighlight>
uint32 consoleSignal = 1L << ConsolePort->mp_SigBit;
uint32 timerSignal = 1L << TimerPort->mp_SigBit;
uint32 userSignal = SIGBREAKF_CTRL_C; /* Defined in <dos/dos.h> */

uint32 signals = IExec->Wait(consoleSignal | timerSignal | userSignal);

if (signals & consoleSignal)
IDOS->Printf("new character\n");

if (signals & timeOutSignal)
IDOS->Printf("timeout\n");

if (signals & userSignal)
IDOS->Printf("User Ctrl-C Abort\n");
</syntaxhighlight>

This code will put the task to sleep waiting for a new character, or the expiration of a time period, or a <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">Ctrl</kbd> + <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">C</kbd> break character issued by the user. Notice that this code checks for an incoming character signal before checking for a timeout. Although a program can check for the occurrence of a particular event by checking whether its signal has occurred, this may lead to busy wait polling. Such polling is wasteful of the processor and is usually harmful to the proper function of the Amiga system. However, if a program needs to do constant processing and also check signals (a compiler for example) SetSignal(0,0) can be used to get a copy of your task's current signals.

<syntaxhighlight>
ULONG SetSignal( ULONG newSignals, ULONG signalSet );
</syntaxhighlight>

SetSignal() can also be used to set or clear the state of the signals. Implementing this can be dangerous and should generally not be done. The following fragment illustrates a possible use of SetSignal().

<syntaxhighlight>
uint32 signals = SetSignal(0,0); /* Get current state of signals */

if (signals & SIGBREAKF_CTRL_C) /* Check for Ctrl-C. */
{
IDOS->Printf("Break\n"); /* Ctrl-C signal has been set. */
IExec->SetSignal(0, SIGBREAKF_CTRL_C) /* Clear Ctrl-C signal. */
}
</syntaxhighlight>

==== Looking for Break Keys ====

One common usage of signals on the Amiga is for processing a user break. The OS reserves 16 of a tasks 32 signals for system use. Four of those 16 signals are used to tell a task about the <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">Ctrl</kbd> + <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">C</kbd>, <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">D</kbd>, <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">E</kbd>, and <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">F</kbd> break keys. An application can process these signals. Usually, only CLI-based programs receive these signals because the Amiga's console handler is about the only user input source that sets these signals when it sees the <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">Ctrl</kbd> + <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">C</kbd>, <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">D</kbd>, <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">E</kbd>, and <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">F</kbd> key presses.

The signal masks for each of these key presses are defined in <dos/dos.h>:

<syntaxhighlight>
SIGBREAKF_CTRL_C
SIGBREAKF_CTRL_D
SIGBREAKF_CTRL_E
SIGBREAKF_CTRL_F
</syntaxhighlight>

Note that these are ''bit masks'' and '''not''' ''bit numbers''.

=== Generating a Signal ===

Signals may be generated from both tasks and system interrupts with the Signal() function.

<syntaxhighlight>
VOID Signal( struct Task *task, ULONG signalSet );
</syntaxhighlight>

For example Signal(tc,mask) would signal the task with the specified mask signals. More than one signal can be specified in the mask. The following example code illustrates Wait() and Signal().

<syntaxhighlight>
// signals.c

#include <exec/types.h>
#include <exec/memory.h>
#include <dos/dos.h>

#include <proto/exec.h>
#include <proto/dos.h>

static CONST_STRPTR VersTag = "$VER: signals 53.1 (20.6.2012)";

void subtaskcode(void); /* prototype for our subtask routine */

struct Task *maintask = NULL;
uint32 mainsig = 0;

int main()
{
BOOL Done = FALSE;
BOOL WaitingForSubtask = TRUE;

/* We must allocate any special signals we want to receive. */
int8 mainsignum = IExec->AllocSignal(-1);
if (mainsignum == -1)
IDOS->Printf("No signals available\n");
else
{
mainsig = 1U << mainsignum; /* subtask can access this global */
maintask = IExec->FindTask(NULL); /* subtask can access this global */

IDOS->Printf("We alloc a signal, create a task, wait for signals\n");

struct Task *subtask = IDOS->CreateTaskTags("subtask", 0, subtaskcode, 16000, TAG_END);

if (subtask == NULL)
IDOS->Printf("Can't create subtask\n");
else
{
IDOS->Printf("After subtask signals, press CTRL-C or CTRL-D to exit\n");

while (!Done || WaitingForSubtask)
{
/* Wait on the combined mask for all of the signals we are
* interested in. All processes have the CTRL_C thru CTRL_F
* signals. We're also Waiting on the mainsig we allocated
* for our subtask to signal us with. We could also Wait on
* the signals of any ports/windows our main task created ... */

uint32 wakeupsigs = IExec->Wait(mainsig | SIGBREAKF_CTRL_C | SIGBREAKF_CTRL_D);

/* Deal with all signals that woke us up - may be more than one */
if (wakeupsigs & mainsig)
{
IDOS->Printf("Signalled by subtask\n");
WaitingForSubtask = FALSE; /* OK to kill subtask now */
}

if (wakeupsigs & SIGBREAKF_CTRL_C)
{
IDOS->Printf("Got CTRL-C signal\n");
Done = TRUE;
}

if(wakeupsigs & SIGBREAKF_CTRL_D)
{
IDOS->Printf("Got CTRL-D signal\n");
Done = TRUE;
}
}
}

IExec->FreeSignal(mainsignum);
}
}

void subtaskcode(void)
{
IExec->Signal(maintask, mainsig);
IExec->RemTask(0); // Remove myself from the system.
}
</syntaxhighlight>

== Reserved System Signals ==

There are 16 signal bits which are reserved for system use. Applications are never allowed to use these signal bits unless explicitly documented (e.g. SIGF_SINGLE).

=== SIGB_ABORT ===

Reserved for system use.

=== SIGB_CHILD ===

Reserved for system use.

=== SIGB_SINGLE (SIGB_BLIT) ===

When a system function needs a Task to stop and IExec->Wait() for a single signal it will use SIGB_SINGLE.

This signal used to be named SIGB_BLIT when it was used to wait on the classic hardware blitter.

=== SIGB_INTUITION ===

Reserved for system use.

=== SIGB_NET ===

Reserved for system use.

=== SIGB_DOS ===

SIGB_DOS is currently used as the wait signal bit for the embedded message port in the process structure. This message port is initialised by the IDOS->CreateNewProc() function. This message port is used by default for DosPacket transactions via IDOS->DoPkt() and IDOS->WaitPkt() and it is also used for sending the initial ACTION_STARTUP DosPacket for DOS handlers. This message port is also where the workbench.library sends the initial struct WBStartup message to every process it starts.

=== SIGBREAKB_CTRL_C ===

The SIGBREAKB_CTRL_C signal bit is used extensively as the general purpose "Break" signal. It is used by all shell handler commands
and many applications to invoke a normal exit of the program. It is up to all applications to follow this recommendation.

Applications should never crash or generally misbehave when receiving a SIGBREAKB_CTRL_C signal bit from any source.

=== SIGBREAKB_CTRL_D ===

The SIGBREAKB_CTRL_D signal bit is used mostly by the shell handler to stop execution of a script file or non-interactive stream. It may also be used by applications.

Applications should never crash or generally misbehave when receiving a SIGBREAKB_CTRL_D signal bit from any source.

=== SIGBREAKB_CTRL_E ===

The SIGBREAKB_CTRL_E signal bit is not currently used by the shell handler but may be used by some other handlers, OS subsystems or multi-process applications for general undefined inter process signaling.

Applications should never crash or generally misbehave when receiving a SIGBREAKB_CTRL_E signal bit from any source.

=== SIGBREAKB_CTRL_F ===

The SIGBREAKB_CTRL_F signal bit is not currently used by the shell handler but may be used by some other handlers, OS subsystems or multi-process applications for general undefined inter process signaling.

Applications should never crash or generally misbehave when receiving a SIGBREAKB_CTRL_F signal bit from any source.

== Signalling with SIGB_SINGLE ==

Many of a task's 32 signal bits are reserved for the operating system's private use, but, like any good rule, there is an exception. One of these bits, the SIGB_SINGLE bit, can be useful to some applications, if used correctly.

Many system functions need to put their task to sleep while waiting for a single event, which requires using one of the task's signals. Rather than forcing each of these system functions to allocate a signal, then Wait(), then deallocate the signal, the operating system
has permanently allocated one signal, the SIGB_SINGLE, for this type of signalling. When a system function needs stop a task to Wait()
for a single signal, it can use SIGB_SINGLE.

The only purpose a program can use SIGB_SINGLE for is Wait()ing because the task cannot call any system functions while it is using SIGB_SINGLE. A program that calls system functions while using SIGB_SINGLE can cause itself and the operating system serious problems because the system functions can use SIGB_SINGLE as well. If a program calls a system function while using SIGB_SINGLE, two bad
things can happen:

1) The errant task's event takes place before the system function waits on SIGB_SINGLE (or while the system function is waiting on
SIGB_SINGLE). In this case, the system function will think its event has taken place because its signal became set. The errant task will never find out that its event has taken place, as the system function will clear the SIGB_SINGLE bit after Wait()ing on it.

2) The errant task's event and the system function's event take place while the system function is waiting on SIGB_SINGLE. In this case,
the system function will function normally, clear the SIGB_SINGLE bit, and exit. The errant task will never know that its event has
taken place.

Before Wait()ing on SIGB_SINGLE, clear it using SetSignal():

<syntaxhighlight>
IExec->SetSignal(0, SIGF_SINGLE); // Note SIGF_SINGLE is the bit mask. SIGB_SINGLE is the signal bit.
</syntaxhighlight>

This step is necessary because it is possible that the last system function that used the SIGB_SINGLE signal did not clear the SIGB_SINGLE bit.

Also, an application should not wait on other signals while it is waiting on SIGB_SINGLE. Waiting on other signals at the same time
makes it possible for a program to wake up while the SIGB_SINGLE is still outstanding. If this happens, the program will still have to
go back to sleep, which requires calling a system function.

=== SIGB_SINGLE Example ===

Below is a simple example of using the SIGB_SINGLE signal. It starts a child process and waits for that child process to signal
the main process using the SIGB_SINGLE signal.

<syntaxhighlight>
// This example program illustrates simple usage of the SIGB_SINGLE
// signal for "single shot" signalling. This signal is one of the
// system private signals, but applications can use it in certain
// cases, but only if used carefully. Specifically, applications
// should use it only to Wait() on, and using only that signal
// (applications cannot Wait() on other signals in the same
// Wait()). Not following these rules can cause serious system
// problems.

#include <exec/types.h>
#include <exec/memory.h>
#include <dos/dosextens.h>
#include <dos/dostags.h>

#include <proto/exec.h>
#include <proto/dos.h>

#include <stdio.h>

int32 childprocesscode(void); /* prototype for our childprocess routine. */

struct Process *mainprocess = NULL, *childprocess = NULL;
UBYTE childprocessname[] = "RKM_signal_childprocess";

BPTR output;

int main(int argc, char **argv)
{
if (output = IDOS->Open("CONSOLE:", MODE_OLDFILE)) /* Open the console for the */
/* child process. */
{
mainprocess = (struct Process *)IExec->FindTask(NULL); /* childprocess can */
/* access this global.*/

if (childprocess = IDOS->CreateNewProcTags(
NP_Entry, childprocesscode, /* The child process */
NP_Name, childprocessname,
NP_Output, output,
NP_FreeSeglist, FALSE,
NP_CloseOutput, TRUE,
NP_Child, TRUE,
TAG_END))
{
IDOS->Printf("Main Process: Created a child process and waiting on SIGB_SINGLE.\n");

IDOS->FFlush(IDOS->Output()); /* Make sure the Printf() above appears */
/* in the console window before the child */
/* process starts printing to the console. */

IExec->SetSignal(0, SIGF_SINGLE); /* Use SIGF_SINGLE only after */
/* clearing it. */

/* Wake up the child. */
IExec->Signal((struct Task *)childprocess, SIGBREAKF_CTRL_F);

IExec->Wait(SIGF_SINGLE); /* Only use SIGF_SINGLE for Wait()ing and */
/* Wait on that signal alone! */

IDOS->Printf("Main Process: Received signal from child.\n");
}
else
IDOS->Printf("Main Process: Can't create child process. Exiting.\n");
}
else
IDOS->Printf("Main Process: Can't open CONSOLE:. Exiting.\n");
}

int32 childprocesscode(void) /* This function is what CreateNewProcTags() */
{ /* loads as the child process. This child */
/* signals the parent using SIGF_SINGLE. */

/* Wait for a startup signal. This is to allow the parent process to
* print its banner message and clear SIGF_SINGLE.
*/
IExec->Wait(SIGBREAKF_CTRL_F);

IDOS->Printf("Child Process: I'm alive and starting a 5 second TimeDelay()");
IDOS->FFlush(IDOS->Output());

for (uint32 x = 0; x < 5; x++)
{
IDOS->Delay(50); /* Delay for 5 seconds, printing a */
IDOS->Printf(" ."); /* dot during each second. */
}

IDOS->Delay(50);

IDOS->Printf(" Finished.\n");
IDOS->Printf("Child Process: Signalling main process and exiting. Bye.\n");
IDOS->FFlush(IDOS->Output());

IExec->Signal((struct Task *)mainprocess, SIGF_SINGLE); /* Finished waiting, */
/* signal the main */
/* process and exit */
/* child process. */
return 0;
}
</syntaxhighlight>

== Function Reference ==

The following chart gives a brief description of the Exec functions that control task signalling. See the SDK for details about each call.

{| class="wikitable"
! Exec Signal Function
! Description
|-
| AllocSignal()
| Allocate a signal bit.
|-
| FreeSignal()
| Free a signal bit allocated with AllocSignal().
|-
| SetSignal()
| Query or set the state of the signals for the current task.
|-
| Signal()
| Signal a task by setting signal bits in its Task structure.
|-
| Wait()
| Wait for one or more signals from other tasks or interrupts.
|}

Exec Signals

2023-09-13T07:15:21Z

Frédéric Khannouf: /* SIGBREAKB_CTRL_F */ Typo fixes

== Exec Signals ==

[[Exec Tasks|Tasks]] often need to coordinate with other concurrent system activities (like other [[Exec Tasks|tasks]] and [[Exec Interrupts|interrupts]]). This coordination is handled by Exec through the synchronized exchange of specific event indicators called ''signals''.

This is the primary mechanism responsible for all inter-task communication and synchronization on the Amiga. This signal mechanism operates at a low level and is designed for high performance. Signals are used extensively by the Exec message system as a way to indicate the arrival of an inter-task message. The message system is described in more detail in [[Exec Messages and Ports]].

{{Note|title=Not for Beginners.|text=This section concentrates on details about signals that most applications do not need to understand for general Amiga programming. For a general overview of signals, see [[Introduction to Exec]].}}

== The Signal System ==

The signal system is designed to support independent simultaneous events, so several signals can occur at the same time. Each task has 32 independent signals, 16 of which are pre-allocated for use by the operating system. The signals in use by a particular task are represented as bits in a 32-bit field in its Task structure (<exec/tasks.h>). Two other 32-bit fields in the Task structure indicate which signals the task is waiting for, and which signals have been received.

Signals are ''task relative''. A task can only allocate its own signals, and may only wait on its own signals. In addition, a task may assign its own significance to a particular signal. Signals are not broadcast to all tasks; they are directed only to individual tasks. A signal has meaning to the task that defined it and to those tasks that have been informed of its meaning.

For example, signal bit 12 may indicate a timeout event to one task, but to another task it may indicate a message arrival event. You can never wait on a signal that you did not directly or indirectly allocate yourself, and any other task that wishes to signal you must use a signal that ''you'' allocated.

=== Signal Allocation ===

As mentioned above, a task assigns its own meaning to a particular signal. Because certain system libraries may occasionally require the use of a signal, there is a convention for signal allocation. It is unwise ever to make assumptions about which signals are actually in use.

Before a signal can be used, it must be allocated with the AllocSignal() function. When a signal is no longer needed, it should be freed for reuse with FreeSignal().

<syntaxhighlight>
BYTE AllocSignal( LONG signalNum );
VOID FreeSignal( LONG signalNum );
</syntaxhighlight>

AllocSignal() marks a signal as being in use and prevents the accidental use of the same signal for more than one event. You may ask for either a specific signal number, or more commonly, you would pass -1 to request the next available signal. The state of the newly allocated signal is cleared (ready for use). Generally it is best to let the system assign you the next free signal. Of the 32 available signals, the lower 16 are reserved for system use (see [[#Reserved_System_Signals|Reserved System Signals]]). This leaves the upper 16 signals free for application programs to allocate. Other subsystems that you may call depend on AllocSignal().

The following example asks for the next free signal to be allocated for its use:

<syntaxhighlight>
if (-1 == (signal = IExec->AllocSignal(-1)))
IDOS->Printf("no signal bits available\n");
else
{
IDOS->Printf("allocated signal number %ld\n", signal);
/* Other code could go here */
IExec->FreeSignal(signal)
}
</syntaxhighlight>

The value returned by AllocSignal() is a signal bit number. This value cannot be used directly in calls to signal-related functions without first being converted to a mask:

<syntaxhighlight>
uint32 mask = 1UL << signal;
or
uint32 mask = (uint32)1 << signal;
</syntaxhighlight>

It is important to realize that signal bit allocation is relevant ''only'' to the running task. You ''cannot'' allocate a signal from another task. Note that functions which create a signal MsgPort will allocate a signal from the task that calls the function. Such functions include OpenWindow() and AllocSysObject(). For this reason, only the creating task may Wait() (directly or indirectly) on the MsgPort's signal. Functions which call Wait() include DoIO(), WaitIO() and WaitPort().

=== Waiting for a Signal ===

Signals are most often used to wake up a task upon the occurrence of some external event. Applications call the Exec Wait() function, directly or indirectly, in order to enter a wait state until some external event triggers a signal which awakens the task.

Though signals are usually not used to interrupt an executing task, they can be used this way. Task ''exceptions'', described in [[Exec_Interrupts|Exec Interrupts]], allow signals to act as a task-local interrupt.

The Wait() function specifies the set of signals that will wake up the task and then puts the task to sleep (into the waiting state).

<syntaxhighlight>
ULONG Wait( ULONG signalSet );
</syntaxhighlight>

Any one signal or any combination of signals from this set are sufficient to awaken the task. Wait() returns a mask indicating which signals satisfied the Wait() call. Note that when signals are used in conjunction with a message port, a set signal bit does not necessarily mean that there is a message at the message port.

See [[Exec_Messages_and_Ports|Exec Messages and Ports]] for details about proper handling of messages.

Because tasks (and interrupts) normally execute asynchronously, it is often possible to receive a particular signal before a task actually Wait()s for it. In such cases the Wait() will be immediately satisfied, and the task will not be put to sleep.

The Wait() function implicitly clears those signal bits that satisfied the wait condition. This effectively resets those signals for reuse. However, keep in mind that a task might get more signals while it is still processing the previous signal. If the same signal is received multiple times and the signal bit is not cleared between them, some signals will go unnoticed.

Be aware that using Wait() will break a Forbid() or Disable() state. Wait() cannot be used in supervisor mode or within interrupts.

A task may Wait() for a combination of signal bits and will wake up when any of the signals occur. Wait() returns a signal mask specifying which signal or signals were received. Usually the program must check the returned mask for each signal it was waiting on and take the appropriate action for each that occurred. The order in which these bits are checked is often important.

Here is a hypothetical example of a process that is using the console and timer devices, and is waiting for a message from either device and a possible break character issued by the user:

<syntaxhighlight>
uint32 consoleSignal = 1L << ConsolePort->mp_SigBit;
uint32 timerSignal = 1L << TimerPort->mp_SigBit;
uint32 userSignal = SIGBREAKF_CTRL_C; /* Defined in <dos/dos.h> */

uint32 signals = IExec->Wait(consoleSignal | timerSignal | userSignal);

if (signals & consoleSignal)
IDOS->Printf("new character\n");

if (signals & timeOutSignal)
IDOS->Printf("timeout\n");

if (signals & userSignal)
IDOS->Printf("User Ctrl-C Abort\n");
</syntaxhighlight>

This code will put the task to sleep waiting for a new character, or the expiration of a time period, or a <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">Ctrl</kbd> + <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">C</kbd> break character issued by the user. Notice that this code checks for an incoming character signal before checking for a timeout. Although a program can check for the occurrence of a particular event by checking whether its signal has occurred, this may lead to busy wait polling. Such polling is wasteful of the processor and is usually harmful to the proper function of the Amiga system. However, if a program needs to do constant processing and also check signals (a compiler for example) SetSignal(0,0) can be used to get a copy of your task's current signals.

<syntaxhighlight>
ULONG SetSignal( ULONG newSignals, ULONG signalSet );
</syntaxhighlight>

SetSignal() can also be used to set or clear the state of the signals. Implementing this can be dangerous and should generally not be done. The following fragment illustrates a possible use of SetSignal().

<syntaxhighlight>
uint32 signals = SetSignal(0,0); /* Get current state of signals */

if (signals & SIGBREAKF_CTRL_C) /* Check for Ctrl-C. */
{
IDOS->Printf("Break\n"); /* Ctrl-C signal has been set. */
IExec->SetSignal(0, SIGBREAKF_CTRL_C) /* Clear Ctrl-C signal. */
}
</syntaxhighlight>

==== Looking for Break Keys ====

One common usage of signals on the Amiga is for processing a user break. The OS reserves 16 of a tasks 32 signals for system use. Four of those 16 signals are used to tell a task about the <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">Ctrl</kbd> + <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">C</kbd>, <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">D</kbd>, <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">E</kbd>, and <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">F</kbd> break keys. An application can process these signals. Usually, only CLI-based programs receive these signals because the Amiga's console handler is about the only user input source that sets these signals when it sees the <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">Ctrl</kbd> + <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">C</kbd>, <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">D</kbd>, <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">E</kbd>, and <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">F</kbd> key presses.

The signal masks for each of these key presses are defined in <dos/dos.h>:

<syntaxhighlight>
SIGBREAKF_CTRL_C
SIGBREAKF_CTRL_D
SIGBREAKF_CTRL_E
SIGBREAKF_CTRL_F
</syntaxhighlight>

Note that these are ''bit masks'' and '''not''' ''bit numbers''.

=== Generating a Signal ===

Signals may be generated from both tasks and system interrupts with the Signal() function.

<syntaxhighlight>
VOID Signal( struct Task *task, ULONG signalSet );
</syntaxhighlight>

For example Signal(tc,mask) would signal the task with the specified mask signals. More than one signal can be specified in the mask. The following example code illustrates Wait() and Signal().

<syntaxhighlight>
// signals.c

#include <exec/types.h>
#include <exec/memory.h>
#include <dos/dos.h>

#include <proto/exec.h>
#include <proto/dos.h>

static CONST_STRPTR VersTag = "$VER: signals 53.1 (20.6.2012)";

void subtaskcode(void); /* prototype for our subtask routine */

struct Task *maintask = NULL;
uint32 mainsig = 0;

int main()
{
BOOL Done = FALSE;
BOOL WaitingForSubtask = TRUE;

/* We must allocate any special signals we want to receive. */
int8 mainsignum = IExec->AllocSignal(-1);
if (mainsignum == -1)
IDOS->Printf("No signals available\n");
else
{
mainsig = 1U << mainsignum; /* subtask can access this global */
maintask = IExec->FindTask(NULL); /* subtask can access this global */

IDOS->Printf("We alloc a signal, create a task, wait for signals\n");

struct Task *subtask = IDOS->CreateTaskTags("subtask", 0, subtaskcode, 16000, TAG_END);

if (subtask == NULL)
IDOS->Printf("Can't create subtask\n");
else
{
IDOS->Printf("After subtask signals, press CTRL-C or CTRL-D to exit\n");

while (!Done || WaitingForSubtask)
{
/* Wait on the combined mask for all of the signals we are
* interested in. All processes have the CTRL_C thru CTRL_F
* signals. We're also Waiting on the mainsig we allocated
* for our subtask to signal us with. We could also Wait on
* the signals of any ports/windows our main task created ... */

uint32 wakeupsigs = IExec->Wait(mainsig | SIGBREAKF_CTRL_C | SIGBREAKF_CTRL_D);

/* Deal with all signals that woke us up - may be more than one */
if (wakeupsigs & mainsig)
{
IDOS->Printf("Signalled by subtask\n");
WaitingForSubtask = FALSE; /* OK to kill subtask now */
}

if (wakeupsigs & SIGBREAKF_CTRL_C)
{
IDOS->Printf("Got CTRL-C signal\n");
Done = TRUE;
}

if(wakeupsigs & SIGBREAKF_CTRL_D)
{
IDOS->Printf("Got CTRL-D signal\n");
Done = TRUE;
}
}
}

IExec->FreeSignal(mainsignum);
}
}

void subtaskcode(void)
{
IExec->Signal(maintask, mainsig);
IExec->RemTask(0); // Remove myself from the system.
}
</syntaxhighlight>

== Reserved System Signals ==

There are 16 signal bits which are reserved for system use. Applications are never allowed to use these signal bits unless explicitly documented (e.g. SIGF_SINGLE).

=== SIGB_ABORT ===

Reserved for system use.

=== SIGB_CHILD ===

Reserved for system use.

=== SIGB_SINGLE (SIGB_BLIT) ===

When a system function needs a Task to stop and IExec->Wait() for a single signal it will use SIGB_SINGLE.

This signal used to be named SIGB_BLIT when it was used to wait on the classic hardware blitter.

=== SIGB_INTUITION ===

Reserved for system use.

=== SIGB_NET ===

Reserved for system use.

=== SIGB_DOS ===

SIGB_DOS is currently used as the wait signal bit for the embedded message port in the process structure. This message port is initialised by the IDOS->CreateNewProc() function. This message port is used by default for DosPacket transactions via IDOS->DoPkt() and IDOS->WaitPkt() and it is also used for sending the initial ACTION_STARTUP DosPacket for DOS handlers. This message port is also where the workbench.library sends the initial struct WBStartup message to every process it starts.

=== SIGBREAKB_CTRL_C ===

The SIGBREAKB_CTRL_C signal bit is used extensively as the general purpose "Break" signal. It is used by all shell handler commands
and many applications to invoke a normal exit of the program. It is up to all applications to follow this recommendation.

Applications should never crash or generally misbehave when receiving a SIGBREAKB_CTRL_C signal bit from any source.

=== SIGBREAKB_CTRL_D ===

The SIGBREAKB_CTRL_D signal bit is used mostly by the shell handler to stop execution of a script file or non-interactive stream. It may also be used by applications.

Applications should never crash or generally misbehave when receiving a SIGBREAKB_CTRL_D signal bit from any source.

=== SIGBREAKB_CTRL_E ===

The SIGBREAKB_CTRL_E signal bit is not currently used by the shell handler but may be used by some other handlers, OS subsystems or multi-process applications for general undefined inter process signalling.

Applications should never crash or generally misbehave when receiving a SIGBREAKB_CTRL_E signal bit from any source.

=== SIGBREAKB_CTRL_F ===

The SIGBREAKB_CTRL_F signal bit is not currently used by the shell handler but may be used by some other handlers, OS subsystems or multi-process applications for general undefined inter process signaling.

Applications should never crash or generally misbehave when receiving a SIGBREAKB_CTRL_F signal bit from any source.

== Signalling with SIGB_SINGLE ==

Many of a task's 32 signal bits are reserved for the operating system's private use, but, like any good rule, there is an exception. One of these bits, the SIGB_SINGLE bit, can be useful to some applications, if used correctly.

Many system functions need to put their task to sleep while waiting for a single event, which requires using one of the task's signals. Rather than forcing each of these system functions to allocate a signal, then Wait(), then deallocate the signal, the operating system
has permanently allocated one signal, the SIGB_SINGLE, for this type of signalling. When a system function needs stop a task to Wait()
for a single signal, it can use SIGB_SINGLE.

The only purpose a program can use SIGB_SINGLE for is Wait()ing because the task cannot call any system functions while it is using SIGB_SINGLE. A program that calls system functions while using SIGB_SINGLE can cause itself and the operating system serious problems because the system functions can use SIGB_SINGLE as well. If a program calls a system function while using SIGB_SINGLE, two bad
things can happen:

1) The errant task's event takes place before the system function waits on SIGB_SINGLE (or while the system function is waiting on
SIGB_SINGLE). In this case, the system function will think its event has taken place because its signal became set. The errant task will never find out that its event has taken place, as the system function will clear the SIGB_SINGLE bit after Wait()ing on it.

2) The errant task's event and the system function's event take place while the system function is waiting on SIGB_SINGLE. In this case,
the system function will function normally, clear the SIGB_SINGLE bit, and exit. The errant task will never know that its event has
taken place.

Before Wait()ing on SIGB_SINGLE, clear it using SetSignal():

<syntaxhighlight>
IExec->SetSignal(0, SIGF_SINGLE); // Note SIGF_SINGLE is the bit mask. SIGB_SINGLE is the signal bit.
</syntaxhighlight>

This step is necessary because it is possible that the last system function that used the SIGB_SINGLE signal did not clear the SIGB_SINGLE bit.

Also, an application should not wait on other signals while it is waiting on SIGB_SINGLE. Waiting on other signals at the same time
makes it possible for a program to wake up while the SIGB_SINGLE is still outstanding. If this happens, the program will still have to
go back to sleep, which requires calling a system function.

=== SIGB_SINGLE Example ===

Below is a simple example of using the SIGB_SINGLE signal. It starts a child process and waits for that child process to signal
the main process using the SIGB_SINGLE signal.

<syntaxhighlight>
// This example program illustrates simple usage of the SIGB_SINGLE
// signal for "single shot" signalling. This signal is one of the
// system private signals, but applications can use it in certain
// cases, but only if used carefully. Specifically, applications
// should use it only to Wait() on, and using only that signal
// (applications cannot Wait() on other signals in the same
// Wait()). Not following these rules can cause serious system
// problems.

#include <exec/types.h>
#include <exec/memory.h>
#include <dos/dosextens.h>
#include <dos/dostags.h>

#include <proto/exec.h>
#include <proto/dos.h>

#include <stdio.h>

int32 childprocesscode(void); /* prototype for our childprocess routine. */

struct Process *mainprocess = NULL, *childprocess = NULL;
UBYTE childprocessname[] = "RKM_signal_childprocess";

BPTR output;

int main(int argc, char **argv)
{
if (output = IDOS->Open("CONSOLE:", MODE_OLDFILE)) /* Open the console for the */
/* child process. */
{
mainprocess = (struct Process *)IExec->FindTask(NULL); /* childprocess can */
/* access this global.*/

if (childprocess = IDOS->CreateNewProcTags(
NP_Entry, childprocesscode, /* The child process */
NP_Name, childprocessname,
NP_Output, output,
NP_FreeSeglist, FALSE,
NP_CloseOutput, TRUE,
NP_Child, TRUE,
TAG_END))
{
IDOS->Printf("Main Process: Created a child process and waiting on SIGB_SINGLE.\n");

IDOS->FFlush(IDOS->Output()); /* Make sure the Printf() above appears */
/* in the console window before the child */
/* process starts printing to the console. */

IExec->SetSignal(0, SIGF_SINGLE); /* Use SIGF_SINGLE only after */
/* clearing it. */

/* Wake up the child. */
IExec->Signal((struct Task *)childprocess, SIGBREAKF_CTRL_F);

IExec->Wait(SIGF_SINGLE); /* Only use SIGF_SINGLE for Wait()ing and */
/* Wait on that signal alone! */

IDOS->Printf("Main Process: Received signal from child.\n");
}
else
IDOS->Printf("Main Process: Can't create child process. Exiting.\n");
}
else
IDOS->Printf("Main Process: Can't open CONSOLE:. Exiting.\n");
}

int32 childprocesscode(void) /* This function is what CreateNewProcTags() */
{ /* loads as the child process. This child */
/* signals the parent using SIGF_SINGLE. */

/* Wait for a startup signal. This is to allow the parent process to
* print its banner message and clear SIGF_SINGLE.
*/
IExec->Wait(SIGBREAKF_CTRL_F);

IDOS->Printf("Child Process: I'm alive and starting a 5 second TimeDelay()");
IDOS->FFlush(IDOS->Output());

for (uint32 x = 0; x < 5; x++)
{
IDOS->Delay(50); /* Delay for 5 seconds, printing a */
IDOS->Printf(" ."); /* dot during each second. */
}

IDOS->Delay(50);

IDOS->Printf(" Finished.\n");
IDOS->Printf("Child Process: Signalling main process and exiting. Bye.\n");
IDOS->FFlush(IDOS->Output());

IExec->Signal((struct Task *)mainprocess, SIGF_SINGLE); /* Finished waiting, */
/* signal the main */
/* process and exit */
/* child process. */
return 0;
}
</syntaxhighlight>

== Function Reference ==

The following chart gives a brief description of the Exec functions that control task signalling. See the SDK for details about each call.

{| class="wikitable"
! Exec Signal Function
! Description
|-
| AllocSignal()
| Allocate a signal bit.
|-
| FreeSignal()
| Free a signal bit allocated with AllocSignal().
|-
| SetSignal()
| Query or set the state of the signals for the current task.
|-
| Signal()
| Signal a task by setting signal bits in its Task structure.
|-
| Wait()
| Wait for one or more signals from other tasks or interrupts.
|}

Icon Library

2021-05-22T21:33:16Z

Frédéric Khannouf: Replaced "Flags", "Activation Flags" and "Gadget Type" with their modern counterparts

= The Icon Library =

The ''.info'' file is the center of interaction between applications and Workbench. To help support the Workbench iconic interface and manage ''.info'' files, the Amiga operating system provides the icon library. The icon library allows you to create icons for data files and directories under program control and examine icons to obtain their Tool Types and other characteristics.

= Icon Library Data Structures =

The preceding sections discussed how icons are used to pass file name arguments to an application run from the Workbench. Workbench allows other types of arguments to be passed in the Tool Types array of an icon. To examine the Tool Types array or find other characteristics of the icon such as its type, applications need to read in the ''.info'' file for the icon.

== The DiskObject Structure ==

The actual data present in the ''.info'' file is organized as a DiskObject structure which is defined in the include file <workbench/workbench.h>. For a complete listing, see the SDK. The DiskObject structure contains the following elements:

<syntaxhighlight>
struct DiskObject
{
UWORD do_Magic; /* magic number at start of file */
UWORD do_Version; /* so we can change structure */
struct Gadget do_Gadget; /* a copy of in core gadget */
UBYTE do_Type;
char *do_DefaultTool;
char **do_ToolTypes;
LONG do_CurrentX;
LONG do_CurrentY;
struct DrawerData *do_DrawerData;
char *do_ToolWindow; /* only applies to tools */
LONG do_StackSize; /* only applies to tools */
};
</syntaxhighlight>

; do_Magic
: A magic number that the icon library looks for to make sure that the file it is reading really contains an icon. It should be the manifest constant WB_DISKMAGIC. PutDiskObject() will put this value in the structure, and GetDiskObject will not believe that a file is really an icon unless this value is correct.

; do_Version
: This provides a way to enhance the .info file in an upwardly-compatible way. It should be WB_DISKVERSION. The icon library will set this value for you and will not believe weird values.

; do_Gadget
: This contains all the imagery for the icon. See the "Gadget Structure" section below for more details.

; do_Type
: The type of the icon; can be set to any of the following values.

:{| class="wikitable"
| WBDISK || The root of a disk
|-
| WBDRAWER || A directory on the disk
|-
| WBTOOL || An executable program
|-
| WBPROJECT || A data file
|-
| WBGARBAGE || The Trashcan directory
|-
| WBKICK || A Kickstart disk
|-
| WBAPPICON || Any object not directly associated with a filing system object, such as a print spooler.
|}

; do_DefaultTool
: Default tools are used for project and disk icons. For projects (data files), the default tool is the program Workbench runs when the project is activated. Any valid AmigaDOS path may be entered in this field such as "SYS:myprogram", "df0:mypaint", "myeditor" or ":work/mytool".

: For disk icons, the default tool is the diskcopy program ("SYS:System/DiskCopy") that will be used when ''this disk is the source'' of a copy.

; do_ToolTypes
: This is an array of free-format strings. Workbench does not enforce any rules on these strings, but they are useful for passing environment information. See the section on "The ToolTypes Array" below for more information.

; do_CurrentX, do_CurrentY
: Drawers have a virtual coordinate system. The user can scroll around in this system using the scroll gadgets on the window that opens when the drawer is activated. Each icon in the drawer has a position in the coordinate system. CurrentX and CurrentY contain the icon's current position in the drawer. Picking a position for a newly created icon can be tricky. NO_ICON_POSITION is a system constant for do_CurrentX and do_CurrentY that instructs Workbench to pick a reasonable place for the icon. Workbench will place the icon in an unused region of the drawer. If there is no space in the drawers window, the icon will be placed just to the right of the visible region.

; do_DrawerData
: If the icon is associated with a directory (WBDISK, WBDRAWER, WBGARBAGE), it needs a DrawerData structure to go with it. This structure contains an Intuition NewWindow structure (see [[Intuition Windows]] for more information):

<syntaxhighlight>
struct DrawerData
{
struct NewWindow dd_NewWindow; /* structure to open window */
LONG dd_CurrentX; /* current x coordinate of origin */
LONG dd_CurrentY; /* current y coordinate of origin */
};
</syntaxhighlight>

: Workbench uses this to hold the current window position and size of the window so it will reopen in the same place.

; do_ToolWindow
: This field is reserved for future use.

; do_StackSize
: This is the size of the stack (in bytes) used for running the tool. If this is NULL, then Workbench will use a reasonable default stack size (currently 4K bytes).

{{Note|title=Stack Size is Taken from the Project Icon|text=When a tool is run ''via the default tool mechanism'' (i.e., a project was activated, not the tool itself), Workbench uses the stack size specified in the project's ''.info'' file and the tool's ''.info'' file is ignored.}}

== The Gadget Structure ==

To hold the icon's image, Workbench uses an Intuition Gadget structure, defined in <intuition/intuition.h>. Workbench restricts some of the values of the gadget. All unused fields should be set to 0 or NULL. The Intuition gadget structure members that Workbench icons use are listed below.

; Width
: This is the width (in pixels) of the icon's active region. Any mouse button press within this range will be interpreted as having selected this icon.

; Height
: This is the height (in pixels) of the icon's active region. Any mouse button press within this range will be interpreted as having selected this icon.

; Flags
: The gadget ''must'' be of type GADGIMAGE. Three highlight modes are supported: GADGHCOMP, GADGHIMAGE, and GADGBACKFILL. GADGHCOMP complements everything within the area defined by CurrentX, CurrentY, Width, Height. GADGHIMAGE uses an alternate selection image. GADGBACKFILL is similar to GADGHCOMP, but ensures that there is no "ring" around the selected image. It does this by first complementing the image, and then flooding all color 3 pixels that are on the border of the image to color 0. All other flag bits should be 0.

; Activation
: The activation should have only RELVERIFY and GADGIMMEDIATE set.

; Type
: The gadget type should be BOOLGADGET.

; GadgetRender
: Set this to an appropriate Image structure.

; SelectRender
: Set this to an appropriate alternate Image structure if and only if the highlight mode is GADGHIMAGE.

The Image structure is typically the same size as the gadget, except that Height is often one pixel less than the gadget height. This allows a blank line between the icon image and the icon name. The image depth ''must'' be 2; PlanePick ''must'' be 3; and PlaneOnOff should be 0. The NextImage field should be null.

= Icon Library Functions =

The icon library functions do all the work needed to read, write and examine an icon's ''.info'' file and corresponding DiskObject structure:

<syntaxhighlight>
struct DiskObject *GetDiskObject(UBYTE *name);
struct DiskObject *GetDiskObjectNew(UBYTE *name);
BOOL PutDiskObject(UBYTE *name, struct DiskObject *diskobj);
void FreeDiskObject(struct DiskObject *diskobj);
BOOL DeleteDiskObject(UBYTE *);

UBYTE *FindToolType(UBYTE **toolTypeArray, UBYTE *typeName);
BOOL MatchToolValue(UBYTE *typeString, UBYTE *value);

struct DiskObject *GetDefDiskObjectNew(LONG type);
BOOL PutDefDiskObject(struct DiskObject *diskobj);

UBYTE *BumpRevision(UBYTE *newbuf, UBYTE *oldname);
</syntaxhighlight>

The icon library routine GetDiskObject() reads an icon's ''.info'' file from disk into a DiskObject structure it creates in memory where it can be examined or altered. PutDiskObject() writes the DiskObject out to disk and FreeDiskObject() frees the memory it used. If you modify any pointers in a DiskObject acquired via GetDiskObject(), replace the old pointers before calling FreeDiskObject() so that the proper memory will be freed.

GetDiskObjectNew() works the same as GetDiskObject() except that if no ''.info'' file is found, a default DiskObject will be created for you. DeleteDiskObject() is for removing ''.info'' files from disk, and the functions GetDefDiskObject() and PutDefDiskObject() allow the default icons to be copied or replaced with new defaults.

Once an icon's ''.info'' file has been read into a DiskObject structure, the functions FindToolType() and MatchToolType() can be used to examine the icon's Tool Types array.

= The Tool Types Array =

Earlier sections discussed how Workbench passes filenames as arguments to a program that's about to run. Workbench also allows other types of arguments to be passed in the Tool Types array of an icon. The Tool Types array is found in the do_ToolTypes field of the icon's DiskObject structure.

In brief, Tool Types is an array of pointers to strings that contain any information an application wants to store such as the program options that were in effect when the icon was created. These strings can be used to encode information which will be available to all applications that read the icon's ''.info'' file. Users can enter and change a selected icon's Tool Types by choosing Information in the Workbench Icons menu.

Workbench does not place many restrictions on the Tool Types array, but there are a few conventions you should follow. A string may be no more than 128 bytes long. The alphabet used is 8-bit ANSI (for example, normal ASCII with foreign-language extensions). This means that users may enter Tool Type strings containing international characters. Avoid special or nonprinting characters. The case of the characters is currently significant, so the string "Window" is not equal to "WINDOW".

The general format for a Tool Types entry is <''name''>=<''value''>[|<''value''>], where <''name''> is the field name and <''value''> is the text to associate with that name. Multiple values for one name may be separated by a vertical bar. The values may be the type of the file, programs that can access the data, parameters to be passed to an application, etc. For example, a paint program might set:

<pre>
FILETYPE = PaintProgram | ILBM
</pre>

This Tool Type indicates that the file is an ILBM, perhaps with some additional chunks of data specific to PaintProgram.

Tool Type strings have few restrictions but there are some reserved Tool Types that are parsed by Workbench itself when an application is started from an icon. The reserved Tool Types are TOOLPRI=''n'' (sets the Exec task priority at which Workbench will start the application), STARTPRI=''n'' (sets the starting order for icons in the Wbstartup drawer), and DONOTWAIT (tells Workbench not to wait for the return of a program started via an icon in the Wbstartup drawer). In addition to the reserved Tool Types, which applications should not use, there are standard Tool Types, which applications should use only in the standard way. For a list of standard Tool Types refer to the [[UI_Style_Guide_Workbench#Tool_Types_and_Default_Tool|Amiga User Interface Style Guide]].

Two routines are provided to help you deal with the Tool Types array. FindToolType() returns the value of a Tool Type element. Using the above example, if you are looking for FILETYPE, the string "PaintProgram|ILBM" will be returned. MatchToolValue() returns nonzero if the specified string is in the reference value string. This routine knows how to parse vertical bars. For example, using the reference value strings of "PaintProgram" or "ILBM", MatchToolValue() will return TRUE for "ILBM" and "PaintProgram" and FALSE for everything else.

= Example of Reading Icons and Parsing Tool Types =

The following example demonstrates icon creation, icon reading and Tool Type parsing in the Workbench environment. When called from the Shell, the example creates a small data file in RAM: and creates or updates a project icon for the data file. The created project icon points to this example as its default tool. When the new project icon is double-clicked, Workbench will invoke the default tool (this example) as a Workbench process, and pass it a description of the project data file as a Workbench argument (WBArg) in the WBStartup message.

<syntaxhighlight>
/*
** iconexample.c - Workbench icon startup, creation, and parsing example
*/

#include <exec/types.h>
#include <libraries/dos.h>
#include <workbench/workbench.h>
#include <workbench/startup.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/icon.h>

#include <stdlib.h>
#include <stdio.h>
#include <string.h>

/* our functions */
void cleanexit(UBYTE *,LONG);
void cleanup(void);
void message(UBYTE *);
BOOL makeIcon(UBYTE *, char **, char *);
BOOL showToolTypes(struct WBArg *);

UBYTE *projname = "RAM:Example_Project";
UBYTE *conwinname = "CON:10/10/620/180/iconexample";

UBYTE deftoolname[] = {"iconexample"};

USHORT IconImageData1[] = {
/* Plane 0 */
0x0000,0x0000,0x0000,0x1000,0x0000,0x0000,0x0000,0x3000,
0x0FFF,0xFFFC,0x0000,0x3000,0x0800,0x0004,0x0000,0x3000,
0x0800,0x07FF,0xFFC0,0x3000,0x08A8,0xA400,0x00A0,0x3000,
0x0800,0x0400,0x0090,0x3000,0x08AA,0xA400,0x0088,0x3000,
0x0800,0x042A,0xA0FC,0x3000,0x082A,0xA400,0x0002,0x3000,
0x0800,0x0400,0x0002,0x3000,0x0800,0xA42A,0xA0A2,0x3000,
0x0800,0x0400,0x0002,0x3000,0x0950,0xA42A,0x8AA2,0x3000,
0x0800,0x0400,0x0002,0x3000,0x082A,0xA400,0x0002,0x3000,
0x0800,0x042A,0x2AA2,0x3000,0x0FFF,0xFC00,0x0002,0x3000,
0x0000,0x0400,0x0002,0x3000,0x0000,0x07FF,0xFFFE,0x3000,
0x0000,0x0000,0x0000,0x3000,0x7FFF,0xFFFF,0xFFFF,0xF000,
/* Plane 1 */
0xFFFF,0xFFFF,0xFFFF,0xE000,0xD555,0x5555,0x5555,0x4000,
0xD000,0x0001,0x5555,0x4000,0xD7FF,0xFFF9,0x5555,0x4000,
0xD7FF,0xF800,0x0015,0x4000,0xD757,0x5BFF,0xFF55,0x4000,
0xD7FF,0xFBFF,0xFF65,0x4000,0xD755,0x5BFF,0xFF75,0x4000,
0xD7FF,0xFBD5,0x5F01,0x4000,0xD7D5,0x5BFF,0xFFFD,0x4000,
0xD7FF,0xFBFF,0xFFFD,0x4000,0xD7FF,0x5BD5,0x5F5D,0x4000,
0xD7FF,0xFBFF,0xFFFD,0x4000,0xD6AF,0x5BD5,0x755D,0x4000,
0xD7FF,0xFBFF,0xFFFD,0x4000,0xD7D5,0x5BFF,0xFFFD,0x4000,
0xD7FF,0xFBD5,0xD55D,0x4000,0xD000,0x03FF,0xFFFD,0x4000,
0xD555,0x53FF,0xFFFD,0x4000,0xD555,0x5000,0x0001,0x4000,
0xD555,0x5555,0x5555,0x4000,0x8000,0x0000,0x0000,0x0000,
};

struct Image iconImage1 =
{
0, 0, /* Top Corner */
52, 22, 2, /* Width, Height, Depth */
&IconImageData1[0], /* Image Data */
0x003, 0x000, /* PlanePick,PlaneOnOff */
NULL /* Next Image */
};

UBYTE *toolTypes[] =
{
"FILETYPE=text",
"FLAGS=BOLD|ITALICS",
NULL
};

struct DiskObject projIcon =
{
WB_DISKMAGIC, /* Magic Number */
WB_DISKVERSION, /* Version */
{ /* Embedded Gadget Structure */
NULL, /* Next Gadget Pointer */
97,12,52,23, /* Left,Top,Width,Height */
GFLG_GADGHIMAGE|GFLG_GADGHBOX, /* Flags */
GACT_IMMEDIATE|GACT_RELVERIFY, /* Activation Flags */
GTYP_BOOLGADGET, /* Gadget Type */
(APTR)&iconImage1, /* Render Image */
NULL, /* Select Image */
NULL, /* Gadget Text */
NULL, /* Mutual Exclude */
NULL, /* Special Info */
0, /* Gadget ID */
NULL /* User Data */
},
WBPROJECT, /* Icon Type */
deftoolname, /* Default Tool */
toolTypes, /* Tool Type Array */
NO_ICON_POSITION, /* Current X */
NO_ICON_POSITION, /* Current Y */
NULL, /* Drawer Structure */
NULL, /* Tool Window */
4000 /* Stack Size */
};

/* Opens and allocations we must clean up */
struct Library *IconBase = NULL;
struct IconIFace *IIcon = NULL;
FILE *conwin = NULL;
LONG olddir = -1;

BOOL FromWb;

int main(int argc, char **argv)
{
struct WBStartup *WBenchMsg;
struct WBArg *wbarg;
FILE *file;
LONG wLen;
SHORT i;

FromWb = (argc==0) ? TRUE : FALSE;

/* Open icon.library */
IconBase = IExec->OpenLibrary("icon.library", 50);
IIcon = (struct IconIFace*)IExec->GetInterface(IconBase, "main", 1, NULL);
if (IIcon == NULL)
cleanexit("Can't open icon.library\n",RETURN_FAIL);

/* If started from CLI, this example will create a small text
* file RAM:Example_Project, and create an icon for the file
* which points to this program as its default tool.
*/
if(!FromWb)
{
/* Make a sample project (data) file */
wLen = -1;
if(file=fopen(projname,"w"))
{
wLen = fprintf(file,"Have a nice day\n");
fclose(file);
}
if(wLen < 0) cleanexit("Error writing data file\n",RETURN_FAIL);

/* Now save/update icon for this data file */
if(makeIcon(projname, toolTypes, deftoolname))
{
IDOS->Printf("%s data file and icon saved.\n",projname);
IDOS->Printf("Use Workbench menu Icon Information to examine the icon.\n");
IDOS->Printf("Then copy this example (iconexample) to RAM:\n");
IDOS->Printf("and double-click the %s project icon\n",projname);
}
else cleanexit("Error writing icon\n",RETURN_FAIL);
}

else /* Else we are FromWb - ie. we were either
* started by a tool icon, or as in this case,
* by being the default tool of a project icon.
*/
{
if(!(conwin = fopen(conwinname,"r+")))
cleanexit("Can't open output window\n",RETURN_FAIL);

WBenchMsg = (struct WBStartup *)argv;

/* Note wbarg++ at end of FOR statement steps through wbargs.
* First arg is our executable (tool). Any additional args
* are projects/icons passed to us via either extend select
* or default tool method.
*/
for(i=0, wbarg=WBenchMsg->sm_ArgList;
i < WBenchMsg->sm_NumArgs;
i++, wbarg++)
{
/* if there's a directory lock for this wbarg, CD there */
olddir = -1;
if((wbarg->wa_Lock)&&(*wbarg->wa_Name))
olddir = IDOS->CurrentDir(wbarg->wa_Lock);

showToolTypes(wbarg);

if((i>0)&&(*wbarg->wa_Name))
fprintf(conwin,"In Main. We could open the %s file here\n",
wbarg->wa_Name);
if(olddir != -1) IDOS->CurrentDir(olddir); /* CD back where we were */
}
IDOS->Delay(500);
}
cleanup();
return RETURN_OK;
}

BOOL makeIcon(UBYTE *name, char **newtooltypes, char *newdeftool)
{
struct DiskObject *dobj;
char *olddeftool;
char **oldtooltypes;
BOOL success = FALSE;

if(dobj = IIcon->GetDiskObject(name))
{
/* If file already has an icon, we will save off any fields we
* need to update, update those fields, put the object, restore
* the old field pointers and then free the object. This will
* preserve any custom imagery the user has, and the user's
* current placement of the icon. If your application does
* not know where the user currently keeps your application,
* you should not update his dobj->do_DefaultTool.
*/
oldtooltypes = dobj->do_ToolTypes;
olddeftool = dobj->do_DefaultTool;

dobj->do_ToolTypes = newtooltypes;
dobj->do_DefaultTool = newdeftool;

success = IIcon->PutDiskObject(name,dobj);

/* we must restore the original pointers before freeing */
dobj->do_ToolTypes = oldtooltypes;
dobj->do_DefaultTool = olddeftool;
IIcon->FreeDiskObject(dobj);
}
/* Else, put our default icon */
if(!success) success = IIcon->PutDiskObject(name,&projIcon);
return(success);
}

BOOL showToolTypes(struct WBArg *wbarg)
{
struct DiskObject *dobj;
char **toolarray;
char *s;
BOOL success = FALSE;

fprintf(conwin,"\nWBArg Lock=0x%lx, Name=%s\n",
wbarg->wa_Lock,wbarg->wa_Name);

if((*wbarg->wa_Name) && (dobj = IIcon->GetDiskObject(wbarg->wa_Name)))
{
fprintf(conwin," We have read the DiskObject (icon) for this arg\n");
toolarray = (char **)dobj->do_ToolTypes;

if(s=(char *)IIcon->FindToolType(toolarray,"FILETYPE"))
{
fprintf(conwin," Found tooltype FILETYPE with value %s\n",s);
}
if(s=(char *)IIcon->FindToolType(toolarray,"FLAGS"))
{
fprintf(conwin," Found tooltype FLAGS with value %s\n",s);
if(IIcon->MatchToolValue(s,"BOLD"))
fprintf(conwin," BOLD flag requested\n");
if(IIcon->MatchToolValue(s,"ITALICS"))
fprintf(conwin," ITALICS flag requested\n");
}
/* Free the diskobject we got */
IIcon->FreeDiskObject(dobj);
success = TRUE;
}
else if(!(*wbarg->wa_Name))
fprintf(conwin," Must be a disk or drawer icon\n");
else
fprintf(conwin," Can't find any DiskObject (icon) for this WBArg\n");
return(success);
}

/* Workbench-started programs with no output window may want to display
* messages in a different manner (requester, window title, etc)
*/
void message(UBYTE *s)
{
if(FromWb && conwin) fprintf(conwin,s,strlen(s));
else if (!FromWb) printf(s);
}

void cleanexit(UBYTE *s, LONG n)
{
if(*s) message(s);
cleanup();
exit(n);
}

void cleanup()
{
if(conwin) fclose(conwin);
IExec->DropInterface((struct Interface*)IIcon);
IExec->CloseLibrary(IconBase);
}
</syntaxhighlight>

= Function Reference =

The following are brief descriptions of the functions in icon.library. See SDK for details on each function call.

{| class="wikitable"
|+ Icon Library Functions
|-
! Function
! Description
|-
| GetDiskObject()
| Read the ''.info'' file of an icon into a DiskObject structure
|-
| GetDiskObjectNew()
| Same as GetDiskObject() but returns a default icon if none exists
|-
| PutDiskObject()
| Write a DiskObject structure to disk as a ''.info'' file
|-
| FreeDiskObject()
| Free the DiskObject structure created by GetDiskObject()
|-
| DeleteDiskObject()
| Deletes a given ''.info'' file from disk
|-
| FindToolType()
| Return the value of an entry in the icon's Tool Type array
|-
| MatchToolValue()
| Check a Tool Type entry against a given value
|-
| GetDefDiskObject()
| Read the default icon for a given icon type
|-
| PutDefDiskObject()
| Replace the default icon for a given icon type
|-
| AddFreeList()
| Add memory you have allocated to a FreeList
|-
| FreeFreeList()
| Free all the memory for entries in the FreeList
|-
| BumpRevision()
| Create a new name for a second copy of a Workbench object
|}

Exec Messages and Ports

2021-01-21T22:36:32Z

Frédéric Khannouf: /* Port2.c */ Put ASOT_Message in upper case

== Exec Messages and Ports ==

For inter-process communication, Exec provides a consistent, high-performance mechanism of messages and ports. This mechanism is used to pass message structures of arbitrary sizes from task to task, interrupt to task, or task to software interrupt. In addition, messages are often used to coordinate operations between cooperating tasks. This section describes many of the details of using messages and ports that the casual Amiga programmer won't need. See [[Introduction_to_Exec|Introduction to Exec]] for a general introduction to using messages and ports.

A ''message'' data structure has two parts: system linkage and message body. The system linkage is used by Exec to attach a given message to its destination. The message body contains the actual data of interest. The message body is any arbitrary data up to 64K bytes in size. The message body data can include pointers to other data blocks of any size.

Messages are always sent to a predetermined destination ''port''. At a port, incoming messages are queued in a first-in-first-out (FIFO) order. There are no system restrictions on the number of ports or the number of messages that may be queued to a port (other than the amount of available system memory).

Messages are always queued by ''reference'', i.e., by a pointer to the message. For performance reasons message copying is not performed. In essence, a message between two tasks is a temporary license for the receiving task to use a portion of the memory space of the sending task; that portion being the message itself. This means that if task A sends a message to task B, the message is still part of the task A context. Task A, however, should not access the message until it has been ''replied''; that is, until task B has sent the message back, using the ReplyMsg() function. This technique of message exchange imposes important restrictions on message access.

== Message Ports ==

Message ports are rendezvous points at which messages are collected. A port may contain any number of outstanding messages from many different originators. When a message arrives at a port, the message is appended to the end of the list of messages for that port, and a pre-specified arrival action is invoked. This action may do nothing, or it may cause a predefined task signal or software interrupt (see [[Exec_Interrupts|Exec Interrupts]]).

Like many Exec structures, ports may be given a symbolic name. Such names are particularly useful for tasks that must rendezvous with dynamically created ports. They are also useful for debugging purposes.

A message port consists of a MsgPort structure as defined in the <exec/ports.h> and <exec/ports.i> include files. The C structure for a port is as follows:

<syntaxhighlight>
struct MsgPort {
struct Node mp_Node;
UBYTE mp_Flags;
UBYTE mp_SigBit;
struct Task *mp_SigTask;
struct List mp_MsgList;
};
</syntaxhighlight>

; mp_Node
: is a standard Node structure. This is useful for tasks that might want to rendezvous with a particular message port by name.

; mp_FLags
: are used to indicate message arrival actions. See the explanation below.

; mp_SigBit
: is the signal bit ''number'' when a port is used with the task signal arrival action.

; mp_SigTask
: is a pointer to the task to be signaled. If a software interrupt arrival action is specified, this is a pointer to the interrupt structure.

; mp_MsgList
: is the list header for all messages queued to this port. (See [[Exec_Lists_and_Queues|Exec Lists and Queues]]).

The mp_Flags field contains a subfield indicated by the PF_ACTION mask. This sub-field specifies the message arrival action that occurs when a port receives a new message.

The possibilities are as follows:

; PA_SIGNAL
: This flag tells Exec to signal the mp_SigTask using signal number mp_SigBit on the arrival of a new message. Every time a message is put to the port another signal will occur regardless of how many messages have been queued to the port.

; PA_SOFTINT
: This flag tells Exec to Cause() a software interrupt when a message arrives at the port. In this case, the mp_SigTask field must contain a pointer to a struct Interrupt rather than a Task pointer. The software interrupt will be Caused every time a message is received.

; PA_IGNORE
: This flag tells Exec to perform no operation other than queuing the message. This action is often used to stop signaling or software interrupts without disturbing the contents of the mp_SigTask field.

It is important to realize that a port's arrival action will occur for each new message queued, and that there is not a one-to-one correspondence between messages and signals. Task signals are only single-bit flags so there is no record of how many times a particular signal occurred. There may be many messages queued and only a single task signal; sometimes however there may be a signal, but no messages. All of this has certain implications when designing code that deals with these actions. Your code should not depend on receiving a signal for every message at your port. All of this is also true for software interrupts.

=== Creating a Message Port ===

To create a new message port use AllocSysObject() with an object type of ASOT_PORT. If you want to make the port ''public'', you will need to use the ASOPORT_Name tag. Don't make a port public when it is not necessary for it to be so.

Prior to V50 of the operating system, functions such as CreatePort() and CreateMsgPort() were often used. Some older applications may even have created their own static message ports by hand. Although all of the older methods still function for backwards compatibility, they should no longer be used.

Using dynamic message ports with ASOT_PORT is the only way to ensure your applications will remain compatible and its message ports automatically freed by the system when required.

=== Deleting a Message Port ===

Before a message port is deleted, all outstanding messages from other tasks must be returned. This is done by getting and replying to all messages at the port until message queue is empty. Of course, there is no need to reply to messages owned by the current task (the task performing the port deletion). Public ports must be removed from the system properly before deallocation. If a signal was allocated for the message port, it must also be freed. FreeSysObject() handles all of this automatically.

Prior to V50 of the operating system, message ports must be freed using the correct corresponding function such as DeletePort() or DeleteMsgPort(). The FreeSysObject() function must only be used on ports which were allocated with AllocSysObject().

=== How to Rendezvous at a Message Port ===

The FindPort() function provides a means of finding the address of a public port given its symbolic name. For example, FindPort("Griffin") will return either the address of the message port named "Griffin" or NULL indicating that no such public port exists. Since FindPort() does not do any arbitration over access to public ports, the usage of FindPort() must be protected with Forbid()/Permit(). Names should be unique to prevent collisions among multiple applications. It is a good idea to use your application name as a prefix for your port name. FindPort() does not arbitrate for access to the port list. The owner of a port might remove it at any time. For these reasons a Forbid()/Permit() pair is required for the use of FindPort(). The port address can no longer be regarded as being valid after Permit() unless your application knows that the port cannot go away (for example, if your application created the port).

The following is an example of how to safely put a message to a specific port:

<syntaxhighlight>
#include <exec/types.h>
#include <exec/ports.h>

BOOL SafePutToPort(struct Message *message, CONST_STRPTR portname)
{
IExec->Forbid();

struct MsgPort *port = IExec->FindPort(portname);
if (port != NULL)
IExec->PutMsg(port,message);

IExec->Permit();

return(port ? TRUE : FALSE); /* If FALSE, the port was not found */

/* Once we've done a Permit(), the port might go away and leave us with
an invalid port address. So we return just a BOOL to indicate whether
the message has been sent or not. */
}
</syntaxhighlight>

== Messages ==

As mentioned earlier, a message contains both system header information and the actual message content. The system header is of the Message form defined in <exec/ports.h>. This structure is as follows:

<syntaxhighlight>
struct Message {
struct Node mn_Node;
struct MsgPort *mn_ReplyPort;
UWORD mn_Length;
};
</syntaxhighlight>

; mn_Node
: is a standard Node structure used for port linkage.

; mn_ReplyPort
: is used to indicate a port to which this message will be returned when a reply is necessary.

; mn_Length
: indicates the total length of the message, including the Message structure itself.

This structure is always attached to the head of all messages. For example, if you want a message structure that contains the ''x'' and ''y'' coordinates of a point on the screen, you could define it as follows:

<syntaxhighlight>
struct XYMessage {
struct Message xy_Msg;
UWORD xy_X;
UWORD xy_Y;
}
</syntaxhighlight>

For this structure, the mn_Length field should be set to sizeof(struct XYMessage).

=== Creating a Message ===

Messages are allocated using AllocSysObject() with an object type of ASOT_MESSAGE. The ASOMSG_ReplyPort tag is set to the reply port if desired. Some messages may be sent in one direction in which case the ASOMSG_ReplyPort tag is not used. The size of the message is indicated with ASOMSG_Length and includes the size of the payload.

<syntaxhighlight>
struct XYMessage xymsg = IExec->AllocSysObjectTags(ASOT_MESSAGE,
ASOMSG_Size, sizeof(struct XYMessage),
ASOMSG_ReplyPort, replyPort,
TAG_END);
</syntaxhighlight>

=== Deleting a Message ===

Messages are freed using FreeSysObject(). Programmers should be careful not to free a message which is still in use or queues in a message port.

=== Putting a Message ===

A message is delivered to a given destination port with the PutMsg() function. The message is queued to the port, and that port's arrival action is invoked. If the action specifies a task signal or a software interrupt, the originating task may temporarily lose the processor while the destination processes the message. If a reply to the message is required, the mn_ReplyPort field must be set up prior to the call to PutMsg().

Here is a code fragment for putting a message to a public port. A complete example is at the end of the article.

<syntaxhighlight>
#include <exec/types.h>
#include <exec/memory.h>
#include <exec/ports.h>
#include <libraries/dos.h>

BOOL SafePutToPort(struct Message *, CONST_STRPTR);

struct XYMessage {
struct Message xy_Msg;
uint16 xy_X;
uint16 xy_Y;
};

int main()
{
struct MsgPort *xyport, *xyreplyport;
struct XYMessage *msg;
BOOL foundport;

/* Allocate the message we're going to send. */
struct XYMessage *xymsg = IExec->AllocSysObjectTags(ASOT_MESSAGE,
ASOMSG_Size, sizeof(struct XYMessage),
TAG_END);

if (xymsg != NULL)
{
/* The replyport we'll use to get response */
if (xyreplyport = IExec->AllocSysObject(ASOT_PORT, NULL)) {

xymsg->xy_Msg.mn_ReplyPort = xyreplyport;
xymsg->xy_X = 10;
xymsg->xy_Y = 20;

/* Now try to send that message to a public port named "xyport".
* If foundport eq 0, the port isn't out there.
*/
if (foundport = SafePutToPort((struct Message *)xymsg, "xyport"))
{

. . . /* Now let's wait till the someone responds... */

}
else IDOS->Printf("Couldn't find 'xyport'\n");

IExec->FreeSysObject(ASOT_PORT, xyreplyport);
else IDOS->Printf("Couldn't create message port\n");

IExec->FreeSysObject(ASOT_MESSAGE, xymsg);
}
else IDOS->Printf("Couldn't get memory for xymessage\n");

return 0;
}
</syntaxhighlight>

=== Waiting for a Message ===

A task may go to sleep waiting for a message to arrive at one or more ports. This technique is widely used on the Amiga as a general form of event notification. For example, it is used extensively by tasks for I/O request completion.

The MsgPort.mp_SigTask field contains the address of the task to be signaled and mp_SigBit contains a preallocated signal number (as described in [[Exec_Tasks|Exec Tasks]]).

You can call the WaitPort() function to wait for a message to arrive at a port. This function will return the first message (it may not be the only) queued to a port. Note that your application must still call GetMsg() to remove the message from the port. If the port is empty, your task will go to sleep waiting for the first message. If the port is not empty, your task will not go to sleep. It is possible to receive a signal for a port without a message being present yet. The code processing the messages should be able to handle this. The following code illustrates WaitPort().

<syntaxhighlight>
struct MsgPort *xyport = IExec->AllocSysObjectTags(ASOT_PORT,
ASOPORT_Name, "xyport",
TAG_END);

if (xyport == NULL)
{
IDOS->Printf("Couldn't create xyport\n");
return RETURN_FAIL;
}

struct XYMessage *xy_msg = IExec->WaitPort(xyport); /* go to sleep until message arrives */
</syntaxhighlight>

A more general form of waiting for a message involves the use of the Wait() function (see [[Exec_Signals|Exec Signals]]). This function waits for task event signals directly. If the signal assigned to the message port occurs, the task will awaken. Using the Wait() function is more general because you can wait for more than one signal. By combining the signal bits from each port into one mask for the Wait() function, a loop can be set up to process all messages at all ports.

Here's an example using Wait():

<syntaxhighlight>
struct XYMessage *xy_msg;
BOOL ABORT = FALSE;

struct MsgPort *xyport = IExec->AllocSysObjectTags(ASOT_PORT,
ASOPORT_Name, "xyport",
TAG_END);

if (xyport != NULL)
{
uint32 portsig = 1 << xyport->mp_SigBit;
uint32 usersig = SIGBREAKF_CTRL_C; /* User can break with CTRL-C. */
for (;;)
{
uint32 signal = IExec->Wait(portsig | usersig); /* Sleep till someone signals. */

if (signal & portsig) /* Got a signal at the msgport. */
{ . . .
}
if (signal & usersig) /* Got a signal from the user. */
{
ABORT = TRUE; /* Time to clean up. */
. . .
}
if (ABORT) break;
}
IExec->FreeSysObject(ASOT_PORT, xyport);
}
else IDOS->Printf("Couldn't create xyport\n");
</syntaxhighlight>

{{Note|text=WaitPort() only returns a pointer to the first message in a port. It does not actually remove the message from the port queue.|title=WaitPort() Does Not Remove A Message}}

=== Getting a Message ===

Messages are usually removed from ports with the GetMsg() function. This function removes the next message at the head of the port queue and returns a pointer to it. If there are no messages in a port, this function returns a zero.

The example below illustrates the use of GetMsg() to print the contents of all messages in a port:

<syntaxhighlight>
while (xymsg = IExec->GetMsg(xyport))
IDOS->Printf("x=%ld y=%ld\n", xymsg->xy_X, xymsg->xy_Y);
</syntaxhighlight>

Certain messages may be more important than others. Because ports impose FIFO ordering, these important messages may get queued behind other messages regardless of their priority. If it is necessary to recognize more important messages, it is easiest to create another port for these special messages.

=== Replying ===

When the operations associated with receiving a new message are finished, it is usually necessary to send the message back to the originator. The receiver replies the message by returning it to the originator using the ReplyMsg() function. This is important because it notifies the originator that the message can be reused or deallocated.

The ReplyMsg() function serves this purpose. It returns the message to the port specified in the mn_ReplyPort field of the message. If this field is zero, no reply is returned.

The previous example can be enhanced to reply to each of its messages:

<syntaxhighlight>
while (xymsg = IExec->GetMsg(xyport)) {
IDOS->Printf("x=%ld y=%ld\n", xymsg->xy_X, xymsg->xy_Y);
IExec->ReplyMsg(xymsg);
}
</syntaxhighlight>

Notice that the reply does not occur until ''after'' the message values have been used.

Often the operations associated with receiving a message involve returning ''results'' to the originator. Typically this is done within the message itself. The receiver places the results in fields defined (or perhaps reused) within the message body before replying the message back to the originator. Receipt of the replied message at the originator reply port indicates it is once again safe for the originator to use or change the values found within the message.

The following are two short example tasks that communicate by sending, waiting for and replying to messages. Run these two programs together.

==== Port1.c ====

<syntaxhighlight>
// port1.c - port and message example, run at the same time as port2.c

#include <exec/types.h>
#include <exec/ports.h>
#include <dos/dos.h>
#include <proto/exec.h>
#include <proto/dos.h>

struct XYMessage {
struct Message xym_Msg;
int16 xy_X;
int16 xy_Y;
};

int main()
{
BOOL ABORT = FALSE;

struct MsgPort *xyport = IExec->AllocSysObjectTags(ASOT_PORT,
ASOPORT_Name, "xyport",
TAG_END);

if (xyport != NULL)
{
uint32 portsig = 1U << xyport->mp_SigBit; /* Give user a `break' signal. */
uint32 usersig = SIGBREAKF_CTRL_C;

IDOS->Printf("Start port2 in another shell. CTRL-C here when done.\n");
do
{ /* port1 will wait forever and reply */
uint32 signal = IExec->Wait(portsig | usersig); /* to messages, until the user breaks. */
struct XYMessage *xymsg = 0;

/* Since we only have one port that might get messages we */
if (signal & portsig) /* have to reply to, it is not really necessary to test for */
{ /* the portsignal. If there is not message at the port, xymsg */

while(xymsg = (struct XYMessage *)IExec->GetMsg(xyport)) /* simply will be NULL. */
{
IDOS->Printf("port1 received: x = %d y = %d\n", xymsg->xy_X, xymsg->xy_Y);

xymsg->xy_X += 50; /* Since we have not replied yet to the owner of */
xymsg->xy_Y += 50; /* xymsg, we can change the data contents of xymsg. */

IDOS->Printf("port1 replying with: x = %d y = %d\n", xymsg->xy_X, xymsg->xy_Y);
IExec->ReplyMsg((struct Message *)xymsg);
}
}

if (signal & usersig) /* The user wants to abort. */
{
while(xymsg = (struct XYMessage *)IExec->GetMsg(xyport)) /* Make sure port is empty. */
IExec->ReplyMsg((struct Message *)xymsg);
ABORT = TRUE;
}
}
while (ABORT == FALSE);
IExec->FreeSysObject(ASOT_PORT, xyport);
}
else IDOS->Printf("Couldn't create 'xyport'\n");
return 0;
}
</syntaxhighlight>

==== Port2.c ====

<syntaxhighlight>
// port2.c - port and message example, run at the same time as port1.c

#include <exec/types.h>
#include <exec/ports.h>
#include <exec/memory.h>
#include <dos/dos.h>
#include <proto/exec.h>
#include <proto/dos.h>

BOOL SafePutToPort(struct Message *, CONST_STRPTR);

struct XYMessage {
struct Message xy_Msg;
int16 xy_X;
int16 xy_Y;
};

int main()
{
struct MsgPort *xyreplyport = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END);

if (xyreplyport != NULL)
{
struct XYMessage *reply = NULL;

struct XYMessage *xymsg = IExec->AllocSysObjectTags(ASOT_MESSAGE,
ASOMSG_Size, sizeof(struct XYMessage),
ASOMSG_ReplyPort, xyreplyport,
TAG_END);

if (xymsg != NULL)
{
xymsg->xy_X = 10; /* our special message information. */
xymsg->xy_Y = 20;

IDOS->Printf("Sending to port1: x = %d y = %d\n", xymsg->xy_X, xymsg->xy_Y);

/* port2 will simply try to put */
if (SafePutToPort((struct Message *)xymsg, "xyport")) /* one message to port1 wait for */
{ /* the reply, and then exit */
IExec->WaitPort(xyreplyport);
if (reply = (struct XYMessage *)IExec->GetMsg(xyreplyport))
IDOS->Printf("Reply contains: x = %d y = %d\n", /* We don't ReplyMsg since */
xymsg->xy_X, xymsg->xy_Y); /* WE initiated the message. */

/* Since we only use this private port for receiving replies, and we sent */
/* only one and got one reply there is no need to cleanup. For a public port, */
/* or if you pass a pointer to the port to another process, it is a very good */
/* habit to always handle all messages at the port before you delete it. */
}
else IDOS->Printf("Can't find 'xyport'; start port1 in a separate shell\n");
IExec->FreeSysObject(ASOT_MESSAGE, xymsg);
}
else IDOS->Printf("Couldn't get memory\n");
IExec->FreeSysObject(ASOT_PORT, xyreplyport);
}
else IDOS->Printf("Couldn't create xyreplyport\n");
return 0;
}

BOOL SafePutToPort(struct Message *message, CONST_STRPTR portname)
{
IExec->Forbid();
struct MsgPort *port = IExec->FindPort(portname);
if (port != NULL) IExec->PutMsg(port, message);
IExec->Permit();
return(port ? TRUE : FALSE); /* FALSE if the port was not found */

/* Once we've done a Permit(), the port might go away and leave us with an invalid port */
} /* address. So we return just a BOOL to indicate whether the message has been sent or not. */
</syntaxhighlight>

== Function Reference ==

The following chart gives a brief description of the Exec functions that control inter-task communication with messages and ports. See the SDK for details about each call.

{| class="wikitable"
! Function
! Description
|-
| AddPort()
| Add a public message port to the system list.
|-
| AllocSysObject(ASOT_PORT)
| Allocate and initialize a new message port.
|-
| FindPort()
| Find a public message port in the system list.
|-
| FreeSysObject(ASOT_PORT)
| Free a message port.
|-
| GetMsg()
| Get next message from the message port.
|-
| PutMsg()
| Put a message to a message port.
|-
| RemPort()
| Remove a message port from the system list.
|-
| ReplyMsg()
| Reply to a message on its reply port.
|}

Exec Messages and Ports

2021-01-21T22:15:20Z

Frédéric Khannouf: /* Port2.c */ Added missing IExec-> to FindPort call

== Exec Messages and Ports ==

For inter-process communication, Exec provides a consistent, high-performance mechanism of messages and ports. This mechanism is used to pass message structures of arbitrary sizes from task to task, interrupt to task, or task to software interrupt. In addition, messages are often used to coordinate operations between cooperating tasks. This section describes many of the details of using messages and ports that the casual Amiga programmer won't need. See [[Introduction_to_Exec|Introduction to Exec]] for a general introduction to using messages and ports.

A ''message'' data structure has two parts: system linkage and message body. The system linkage is used by Exec to attach a given message to its destination. The message body contains the actual data of interest. The message body is any arbitrary data up to 64K bytes in size. The message body data can include pointers to other data blocks of any size.

Messages are always sent to a predetermined destination ''port''. At a port, incoming messages are queued in a first-in-first-out (FIFO) order. There are no system restrictions on the number of ports or the number of messages that may be queued to a port (other than the amount of available system memory).

Messages are always queued by ''reference'', i.e., by a pointer to the message. For performance reasons message copying is not performed. In essence, a message between two tasks is a temporary license for the receiving task to use a portion of the memory space of the sending task; that portion being the message itself. This means that if task A sends a message to task B, the message is still part of the task A context. Task A, however, should not access the message until it has been ''replied''; that is, until task B has sent the message back, using the ReplyMsg() function. This technique of message exchange imposes important restrictions on message access.

== Message Ports ==

Message ports are rendezvous points at which messages are collected. A port may contain any number of outstanding messages from many different originators. When a message arrives at a port, the message is appended to the end of the list of messages for that port, and a pre-specified arrival action is invoked. This action may do nothing, or it may cause a predefined task signal or software interrupt (see [[Exec_Interrupts|Exec Interrupts]]).

Like many Exec structures, ports may be given a symbolic name. Such names are particularly useful for tasks that must rendezvous with dynamically created ports. They are also useful for debugging purposes.

A message port consists of a MsgPort structure as defined in the <exec/ports.h> and <exec/ports.i> include files. The C structure for a port is as follows:

<syntaxhighlight>
struct MsgPort {
struct Node mp_Node;
UBYTE mp_Flags;
UBYTE mp_SigBit;
struct Task *mp_SigTask;
struct List mp_MsgList;
};
</syntaxhighlight>

; mp_Node
: is a standard Node structure. This is useful for tasks that might want to rendezvous with a particular message port by name.

; mp_FLags
: are used to indicate message arrival actions. See the explanation below.

; mp_SigBit
: is the signal bit ''number'' when a port is used with the task signal arrival action.

; mp_SigTask
: is a pointer to the task to be signaled. If a software interrupt arrival action is specified, this is a pointer to the interrupt structure.

; mp_MsgList
: is the list header for all messages queued to this port. (See [[Exec_Lists_and_Queues|Exec Lists and Queues]]).

The mp_Flags field contains a subfield indicated by the PF_ACTION mask. This sub-field specifies the message arrival action that occurs when a port receives a new message.

The possibilities are as follows:

; PA_SIGNAL
: This flag tells Exec to signal the mp_SigTask using signal number mp_SigBit on the arrival of a new message. Every time a message is put to the port another signal will occur regardless of how many messages have been queued to the port.

; PA_SOFTINT
: This flag tells Exec to Cause() a software interrupt when a message arrives at the port. In this case, the mp_SigTask field must contain a pointer to a struct Interrupt rather than a Task pointer. The software interrupt will be Caused every time a message is received.

; PA_IGNORE
: This flag tells Exec to perform no operation other than queuing the message. This action is often used to stop signaling or software interrupts without disturbing the contents of the mp_SigTask field.

It is important to realize that a port's arrival action will occur for each new message queued, and that there is not a one-to-one correspondence between messages and signals. Task signals are only single-bit flags so there is no record of how many times a particular signal occurred. There may be many messages queued and only a single task signal; sometimes however there may be a signal, but no messages. All of this has certain implications when designing code that deals with these actions. Your code should not depend on receiving a signal for every message at your port. All of this is also true for software interrupts.

=== Creating a Message Port ===

To create a new message port use AllocSysObject() with an object type of ASOT_PORT. If you want to make the port ''public'', you will need to use the ASOPORT_Name tag. Don't make a port public when it is not necessary for it to be so.

Prior to V50 of the operating system, functions such as CreatePort() and CreateMsgPort() were often used. Some older applications may even have created their own static message ports by hand. Although all of the older methods still function for backwards compatibility, they should no longer be used.

Using dynamic message ports with ASOT_PORT is the only way to ensure your applications will remain compatible and its message ports automatically freed by the system when required.

=== Deleting a Message Port ===

Before a message port is deleted, all outstanding messages from other tasks must be returned. This is done by getting and replying to all messages at the port until message queue is empty. Of course, there is no need to reply to messages owned by the current task (the task performing the port deletion). Public ports must be removed from the system properly before deallocation. If a signal was allocated for the message port, it must also be freed. FreeSysObject() handles all of this automatically.

Prior to V50 of the operating system, message ports must be freed using the correct corresponding function such as DeletePort() or DeleteMsgPort(). The FreeSysObject() function must only be used on ports which were allocated with AllocSysObject().

=== How to Rendezvous at a Message Port ===

The FindPort() function provides a means of finding the address of a public port given its symbolic name. For example, FindPort("Griffin") will return either the address of the message port named "Griffin" or NULL indicating that no such public port exists. Since FindPort() does not do any arbitration over access to public ports, the usage of FindPort() must be protected with Forbid()/Permit(). Names should be unique to prevent collisions among multiple applications. It is a good idea to use your application name as a prefix for your port name. FindPort() does not arbitrate for access to the port list. The owner of a port might remove it at any time. For these reasons a Forbid()/Permit() pair is required for the use of FindPort(). The port address can no longer be regarded as being valid after Permit() unless your application knows that the port cannot go away (for example, if your application created the port).

The following is an example of how to safely put a message to a specific port:

<syntaxhighlight>
#include <exec/types.h>
#include <exec/ports.h>

BOOL SafePutToPort(struct Message *message, CONST_STRPTR portname)
{
IExec->Forbid();

struct MsgPort *port = IExec->FindPort(portname);
if (port != NULL)
IExec->PutMsg(port,message);

IExec->Permit();

return(port ? TRUE : FALSE); /* If FALSE, the port was not found */

/* Once we've done a Permit(), the port might go away and leave us with
an invalid port address. So we return just a BOOL to indicate whether
the message has been sent or not. */
}
</syntaxhighlight>

== Messages ==

As mentioned earlier, a message contains both system header information and the actual message content. The system header is of the Message form defined in <exec/ports.h>. This structure is as follows:

<syntaxhighlight>
struct Message {
struct Node mn_Node;
struct MsgPort *mn_ReplyPort;
UWORD mn_Length;
};
</syntaxhighlight>

; mn_Node
: is a standard Node structure used for port linkage.

; mn_ReplyPort
: is used to indicate a port to which this message will be returned when a reply is necessary.

; mn_Length
: indicates the total length of the message, including the Message structure itself.

This structure is always attached to the head of all messages. For example, if you want a message structure that contains the ''x'' and ''y'' coordinates of a point on the screen, you could define it as follows:

<syntaxhighlight>
struct XYMessage {
struct Message xy_Msg;
UWORD xy_X;
UWORD xy_Y;
}
</syntaxhighlight>

For this structure, the mn_Length field should be set to sizeof(struct XYMessage).

=== Creating a Message ===

Messages are allocated using AllocSysObject() with an object type of ASOT_MESSAGE. The ASOMSG_ReplyPort tag is set to the reply port if desired. Some messages may be sent in one direction in which case the ASOMSG_ReplyPort tag is not used. The size of the message is indicated with ASOMSG_Length and includes the size of the payload.

<syntaxhighlight>
struct XYMessage xymsg = IExec->AllocSysObjectTags(ASOT_MESSAGE,
ASOMSG_Size, sizeof(struct XYMessage),
ASOMSG_ReplyPort, replyPort,
TAG_END);
</syntaxhighlight>

=== Deleting a Message ===

Messages are freed using FreeSysObject(). Programmers should be careful not to free a message which is still in use or queues in a message port.

=== Putting a Message ===

A message is delivered to a given destination port with the PutMsg() function. The message is queued to the port, and that port's arrival action is invoked. If the action specifies a task signal or a software interrupt, the originating task may temporarily lose the processor while the destination processes the message. If a reply to the message is required, the mn_ReplyPort field must be set up prior to the call to PutMsg().

Here is a code fragment for putting a message to a public port. A complete example is at the end of the article.

<syntaxhighlight>
#include <exec/types.h>
#include <exec/memory.h>
#include <exec/ports.h>
#include <libraries/dos.h>

BOOL SafePutToPort(struct Message *, CONST_STRPTR);

struct XYMessage {
struct Message xy_Msg;
uint16 xy_X;
uint16 xy_Y;
};

int main()
{
struct MsgPort *xyport, *xyreplyport;
struct XYMessage *msg;
BOOL foundport;

/* Allocate the message we're going to send. */
struct XYMessage *xymsg = IExec->AllocSysObjectTags(ASOT_MESSAGE,
ASOMSG_Size, sizeof(struct XYMessage),
TAG_END);

if (xymsg != NULL)
{
/* The replyport we'll use to get response */
if (xyreplyport = IExec->AllocSysObject(ASOT_PORT, NULL)) {

xymsg->xy_Msg.mn_ReplyPort = xyreplyport;
xymsg->xy_X = 10;
xymsg->xy_Y = 20;

/* Now try to send that message to a public port named "xyport".
* If foundport eq 0, the port isn't out there.
*/
if (foundport = SafePutToPort((struct Message *)xymsg, "xyport"))
{

. . . /* Now let's wait till the someone responds... */

}
else IDOS->Printf("Couldn't find 'xyport'\n");

IExec->FreeSysObject(ASOT_PORT, xyreplyport);
else IDOS->Printf("Couldn't create message port\n");

IExec->FreeSysObject(ASOT_MESSAGE, xymsg);
}
else IDOS->Printf("Couldn't get memory for xymessage\n");

return 0;
}
</syntaxhighlight>

=== Waiting for a Message ===

A task may go to sleep waiting for a message to arrive at one or more ports. This technique is widely used on the Amiga as a general form of event notification. For example, it is used extensively by tasks for I/O request completion.

The MsgPort.mp_SigTask field contains the address of the task to be signaled and mp_SigBit contains a preallocated signal number (as described in [[Exec_Tasks|Exec Tasks]]).

You can call the WaitPort() function to wait for a message to arrive at a port. This function will return the first message (it may not be the only) queued to a port. Note that your application must still call GetMsg() to remove the message from the port. If the port is empty, your task will go to sleep waiting for the first message. If the port is not empty, your task will not go to sleep. It is possible to receive a signal for a port without a message being present yet. The code processing the messages should be able to handle this. The following code illustrates WaitPort().

<syntaxhighlight>
struct MsgPort *xyport = IExec->AllocSysObjectTags(ASOT_PORT,
ASOPORT_Name, "xyport",
TAG_END);

if (xyport == NULL)
{
IDOS->Printf("Couldn't create xyport\n");
return RETURN_FAIL;
}

struct XYMessage *xy_msg = IExec->WaitPort(xyport); /* go to sleep until message arrives */
</syntaxhighlight>

A more general form of waiting for a message involves the use of the Wait() function (see [[Exec_Signals|Exec Signals]]). This function waits for task event signals directly. If the signal assigned to the message port occurs, the task will awaken. Using the Wait() function is more general because you can wait for more than one signal. By combining the signal bits from each port into one mask for the Wait() function, a loop can be set up to process all messages at all ports.

Here's an example using Wait():

<syntaxhighlight>
struct XYMessage *xy_msg;
BOOL ABORT = FALSE;

struct MsgPort *xyport = IExec->AllocSysObjectTags(ASOT_PORT,
ASOPORT_Name, "xyport",
TAG_END);

if (xyport != NULL)
{
uint32 portsig = 1 << xyport->mp_SigBit;
uint32 usersig = SIGBREAKF_CTRL_C; /* User can break with CTRL-C. */
for (;;)
{
uint32 signal = IExec->Wait(portsig | usersig); /* Sleep till someone signals. */

if (signal & portsig) /* Got a signal at the msgport. */
{ . . .
}
if (signal & usersig) /* Got a signal from the user. */
{
ABORT = TRUE; /* Time to clean up. */
. . .
}
if (ABORT) break;
}
IExec->FreeSysObject(ASOT_PORT, xyport);
}
else IDOS->Printf("Couldn't create xyport\n");
</syntaxhighlight>

{{Note|text=WaitPort() only returns a pointer to the first message in a port. It does not actually remove the message from the port queue.|title=WaitPort() Does Not Remove A Message}}

=== Getting a Message ===

Messages are usually removed from ports with the GetMsg() function. This function removes the next message at the head of the port queue and returns a pointer to it. If there are no messages in a port, this function returns a zero.

The example below illustrates the use of GetMsg() to print the contents of all messages in a port:

<syntaxhighlight>
while (xymsg = IExec->GetMsg(xyport))
IDOS->Printf("x=%ld y=%ld\n", xymsg->xy_X, xymsg->xy_Y);
</syntaxhighlight>

Certain messages may be more important than others. Because ports impose FIFO ordering, these important messages may get queued behind other messages regardless of their priority. If it is necessary to recognize more important messages, it is easiest to create another port for these special messages.

=== Replying ===

When the operations associated with receiving a new message are finished, it is usually necessary to send the message back to the originator. The receiver replies the message by returning it to the originator using the ReplyMsg() function. This is important because it notifies the originator that the message can be reused or deallocated.

The ReplyMsg() function serves this purpose. It returns the message to the port specified in the mn_ReplyPort field of the message. If this field is zero, no reply is returned.

The previous example can be enhanced to reply to each of its messages:

<syntaxhighlight>
while (xymsg = IExec->GetMsg(xyport)) {
IDOS->Printf("x=%ld y=%ld\n", xymsg->xy_X, xymsg->xy_Y);
IExec->ReplyMsg(xymsg);
}
</syntaxhighlight>

Notice that the reply does not occur until ''after'' the message values have been used.

Often the operations associated with receiving a message involve returning ''results'' to the originator. Typically this is done within the message itself. The receiver places the results in fields defined (or perhaps reused) within the message body before replying the message back to the originator. Receipt of the replied message at the originator reply port indicates it is once again safe for the originator to use or change the values found within the message.

The following are two short example tasks that communicate by sending, waiting for and replying to messages. Run these two programs together.

==== Port1.c ====

<syntaxhighlight>
// port1.c - port and message example, run at the same time as port2.c

#include <exec/types.h>
#include <exec/ports.h>
#include <dos/dos.h>
#include <proto/exec.h>
#include <proto/dos.h>

struct XYMessage {
struct Message xym_Msg;
int16 xy_X;
int16 xy_Y;
};

int main()
{
BOOL ABORT = FALSE;

struct MsgPort *xyport = IExec->AllocSysObjectTags(ASOT_PORT,
ASOPORT_Name, "xyport",
TAG_END);

if (xyport != NULL)
{
uint32 portsig = 1U << xyport->mp_SigBit; /* Give user a `break' signal. */
uint32 usersig = SIGBREAKF_CTRL_C;

IDOS->Printf("Start port2 in another shell. CTRL-C here when done.\n");
do
{ /* port1 will wait forever and reply */
uint32 signal = IExec->Wait(portsig | usersig); /* to messages, until the user breaks. */
struct XYMessage *xymsg = 0;

/* Since we only have one port that might get messages we */
if (signal & portsig) /* have to reply to, it is not really necessary to test for */
{ /* the portsignal. If there is not message at the port, xymsg */

while(xymsg = (struct XYMessage *)IExec->GetMsg(xyport)) /* simply will be NULL. */
{
IDOS->Printf("port1 received: x = %d y = %d\n", xymsg->xy_X, xymsg->xy_Y);

xymsg->xy_X += 50; /* Since we have not replied yet to the owner of */
xymsg->xy_Y += 50; /* xymsg, we can change the data contents of xymsg. */

IDOS->Printf("port1 replying with: x = %d y = %d\n", xymsg->xy_X, xymsg->xy_Y);
IExec->ReplyMsg((struct Message *)xymsg);
}
}

if (signal & usersig) /* The user wants to abort. */
{
while(xymsg = (struct XYMessage *)IExec->GetMsg(xyport)) /* Make sure port is empty. */
IExec->ReplyMsg((struct Message *)xymsg);
ABORT = TRUE;
}
}
while (ABORT == FALSE);
IExec->FreeSysObject(ASOT_PORT, xyport);
}
else IDOS->Printf("Couldn't create 'xyport'\n");
return 0;
}
</syntaxhighlight>

==== Port2.c ====

<syntaxhighlight>
// port2.c - port and message example, run at the same time as port1.c

#include <exec/types.h>
#include <exec/ports.h>
#include <exec/memory.h>
#include <dos/dos.h>
#include <proto/exec.h>
#include <proto/dos.h>

BOOL SafePutToPort(struct Message *, CONST_STRPTR);

struct XYMessage {
struct Message xy_Msg;
int16 xy_X;
int16 xy_Y;
};

int main()
{
struct MsgPort *xyreplyport = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END);

if (xyreplyport != NULL)
{
struct XYMessage *reply = NULL;

struct XYMessage *xymsg = IExec->AllocSysObjectTags(ASOT_MESSAGE,
ASOMSG_Size, sizeof(struct XYMessage),
ASOMSG_ReplyPort, xyreplyport,
TAG_END);

if (xymsg != NULL)
{
xymsg->xy_X = 10; /* our special message information. */
xymsg->xy_Y = 20;

IDOS->Printf("Sending to port1: x = %d y = %d\n", xymsg->xy_X, xymsg->xy_Y);

/* port2 will simply try to put */
if (SafePutToPort((struct Message *)xymsg, "xyport")) /* one message to port1 wait for */
{ /* the reply, and then exit */
IExec->WaitPort(xyreplyport);
if (reply = (struct XYMessage *)IExec->GetMsg(xyreplyport))
IDOS->Printf("Reply contains: x = %d y = %d\n", /* We don't ReplyMsg since */
xymsg->xy_X, xymsg->xy_Y); /* WE initiated the message. */

/* Since we only use this private port for receiving replies, and we sent */
/* only one and got one reply there is no need to cleanup. For a public port, */
/* or if you pass a pointer to the port to another process, it is a very good */
/* habit to always handle all messages at the port before you delete it. */
}
else IDOS->Printf("Can't find 'xyport'; start port1 in a separate shell\n");
IExec->FreeSysObject(ASOT_Message, xymsg);
}
else IDOS->Printf("Couldn't get memory\n");
IExec->FreeSysObject(ASOT_PORT, xyreplyport);
}
else IDOS->Printf("Couldn't create xyreplyport\n");
return 0;
}

BOOL SafePutToPort(struct Message *message, CONST_STRPTR portname)
{
IExec->Forbid();
struct MsgPort *port = IExec->FindPort(portname);
if (port != NULL) IExec->PutMsg(port, message);
IExec->Permit();
return(port ? TRUE : FALSE); /* FALSE if the port was not found */

/* Once we've done a Permit(), the port might go away and leave us with an invalid port */
} /* address. So we return just a BOOL to indicate whether the message has been sent or not. */
</syntaxhighlight>

== Function Reference ==

The following chart gives a brief description of the Exec functions that control inter-task communication with messages and ports. See the SDK for details about each call.

{| class="wikitable"
! Function
! Description
|-
| AddPort()
| Add a public message port to the system list.
|-
| AllocSysObject(ASOT_PORT)
| Allocate and initialize a new message port.
|-
| FindPort()
| Find a public message port in the system list.
|-
| FreeSysObject(ASOT_PORT)
| Free a message port.
|-
| GetMsg()
| Get next message from the message port.
|-
| PutMsg()
| Put a message to a message port.
|-
| RemPort()
| Remove a message port from the system list.
|-
| ReplyMsg()
| Reply to a message on its reply port.
|}

AmigaOS Manual: AmigaDOS Error Messages

2020-12-25T10:26:54Z

Frédéric Khannouf: Missing word 'deletion' at line 222

This appendix lists AmigaDOS errors with their probable causes and suggestions for recovery. These error messages are the output from the system when your program fails or if a command is not executed as the result of a user error. Error messages differ from requesters, which are messages from the system that allow you to enter specific corrections, changes, or input so that the program, script, or command can continue execution. A requester that is not satisfied produces an error.

{| class="wikitable"
! Error !! Messages !! Probable Cause !! Recovery Suggestion
|-
| 103
| Not enough memory available
| Not enough Memory in your Amiga to execute the operation. Memory may be fragmented.
| Close unnecessary windows and applications and re-issue the command. Reboot if this does not work. You may need to add more RAM to your system.
|-
| 105
| Task Table Full
| The Amiga is limited to 20 CLI tasks.
| Try closing a few and then enter the command again.
|-
| 115
| Bad number
| The command requires a numerical argument.
| Use the correct command format.
|-
| 116
| Required argument missing
| The command requires an argument that you did not supply.
| Use the correct command format.
|-
| 117
| Value after keyword missing
| Keyword was specified with no argument.
| Use the correct command format.
|-
| 118
| Wrong number of arguments
| Too few or too many arguments.
| Use the correct command format.
|-
| 119
| Unmatched quotes
| You have an odd number of quotation marks.
| Place double quotation marks at the beginning and end of the path or string.
|-
| 120
| Argument line invalid or too long
| Your command line is incorrect or contains too many arguments.
| Use the correct command format.
|-
| 121
| File is not executable
| You misspelled the command name or the file is not a loadable (program or script) file.
| Retype the file name, ensuring that the file is a program file. To execute a script, the s bit must be set or the EXECUTE command must be used.
|-
| 122
| Invalid resident library during load
| The required library was found but was not the correct type. This could be caused by having an old version of the library or the file is corrupt.
| Try searching for a newer version on the Internet or copying the file from your Workbench disks.
|-
| 202
| Object is in use
| The specified file or directory is being edited by another application or is assigned.
| Stop the application using the file or directory or remove the assignment.
|-
| 203
| Object already exists
| The name specified is assigned to another file or directory.
| Use another name or delete the existing file or directory first.
|-
| 204
| Directory not found
| AmigaDOS cannot find the specified directory.
| Check the directory name and location (use DIR if necessary).
|-
| 205
| Object not found
| AmigaDOS cannot find the specified file or device.
| Check the file name (use DIR) or the device name (use INFO).
|-
| 206
| Invalid window description
| Occurs when specifying a window size for a Shell, ED, or ICONX window. The window may be too big or too small or you omitted an argument. Also occurs with the NEWSHELL command, if a device name is supplied that is not a window.
| Use the correct window specification.
|-
| 209
| Packet request type unknown
| The device handler cannot do the requested operation. For example, the console handler cannot rename things.
| Check the request code passed to device handlers for the appropriate request.
|-
| 210
| Object name invalid
| There is an invalid character in the file name or the file name is too long.
| Retype the name; do not use any invalid characters or exceed the maximum length.
|-
| 211
| Invalid object lock
| The lock code was not recognized by the AmigaDOS call.
| This is a programming fault.
|-
| 212
| Object is not of required type
| You may have specified a file name for an operation that requires a directory name, or vice versa.
| Use the correct name and command format.
|-
| 213
| Disk not validated
| If you have just inserted a disk, the disk validation process may be in progress. It is also possible that the disk is corrupt.
| Wait for the validation process to finish. Watch for drive light to turn off. Allow a minute for floppy disks and several minutes for hard disks. Corrupt disks cannot be validated. If corrupted, try retrieving and copying the files to another disk.
|-
| 214
| Disk is write-protected
| The plastic tab is in the write-protect position or the disk has been lokked.
| Remove the disk, move the tab, and reinsert the disk, use a different disk, or use LOCK OFF command.
|-
| 215
| Rename across devices attempted
| RENAME can move a file from one directory to another, but not from one volume to another.
| Use COPY to copy the file to the destination volume. Delete it from the source volume, if desired. Then use RENAME, if desired.
|-
| 216
| Directory not empty
| You tried to delete a directory that contains file or subdirectories.
| Use the ALL option of DELETE if you wish to delete the directory and its contents.
|-
| 217
| Too many levels
| Directory nesting is too deep.
| Reorganize directories so that there are fewer levels or change directories in stages to reach the desired level.
|-
| 218
| Device (or volume) is not mounted
| If the devices is a floppy disk, it has not been inserted in a drive. If it is another type of device, it has not been mounted, or the name is misspelled.
| Insert the correct floppy disk, mount the device, check the spelling of the device name, revise your MountList/mount file, or assign the device name appropriately.
|-
| 219
| Seek error
| An error occurred while processing a file.
| Be sure that you only SEEK within the file. You cannot SEEK outside the bounds of the file.
|-
| 220
| Comment is too long
| You filenote has exceeded the maximum number of characters (79).
| Use a shorter filenote.
|-
| 221
| Disk is full
| There is not enough room on the disk to perform the requested operation.
| Delete unnecessary files or directories or use a different disk.
|-
| 222
| Object is protected from deletion
| The d (deletable) protection bit of the file or directory is clear.
| If you are certain that you want to delete the file or directory, use PROTECT to set the d bit or use the FORCE option of DELETE.
|-
| 223
| File is write protected
| The w (writable) protection bit of the file is clear.
| If you are certain that you want to overwrite the file, use PROTECT to set the w bit.
|-
| 224
| File is read protected
| The r (readable) protection bit of the file is clear.
| Use PROTECT to set the r bit of the file.
|-
| 225
| Not a valid DOS disk
| The disk in the drive is not an AmigaDOS disk, it has not been formatted, or it is corrupt.
| Be sure you are using the correct disk. If the disk worked previously, use a disk recovery program to salvage its files. Format unformatted disks.
|-
| 226
| No disk in drive
| The disk is not inserted in the specified drive.
| Insert the appropriate disk in the specified drive.
|-
| 232
| No more entries in directory
| The AmigaDOS call EXNEXT has no further entries in the directory you are examining.
| Stop calling EXNEXT.
|-
| 233
| Object is soft link
| Attempt was made to access a soft-link for a device that does not support it.
| No recovery.
|-
| 235
| Bad load file hunk
| The program loaded is corrupted.
| Load a new or original copy of the program.
|-
| 241
| Record lock collision
| Another application is accessing the database.
| Try accessing the database again.
|-
| 242
| Record lock timeout
| Another application has the database entry lokked.
| Try again or quit the other application and retry.
|-
| 303
| Buffer overflow
| Occurs if pattern matching string is too long.
| Make pattern matching string shorter.
|-
| 304
| ***Break
| Occurs if program stopped via <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">Ctrl</kbd> + <kbd class="keyboard-key nowrap" style="border: 1px solid #aaa; border-radius: 0.2em; box-shadow: 0.1em 0.2em 0.2em #ddd; background-color: #f9f9f9; background-image: -moz-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -o-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: -webkit-linear-gradient(top, #eee, #f9f9f9, #eee); background-image: linear-gradient(to bottom, #eee, #f9f9f9, #eee); padding: 0.1em 0.3em; font-family: inherit; font-size: 0.85em;">C</kbd>.
| No recovery
|-
| 305
| File not executable
| The e (executable) bit of the file is clear.
| Same as Error 121.
|}

Commodities Exchange Library

2020-10-22T08:29:04Z

Frédéric Khannouf: Replaced a "stdio" printf by a DOS Printf, as stdio.h is not included in this source example

{{CodeReview}}
== Commodities Exchange Library ==

This article describes Commodities Exchange, the library of routines used to add a custom input handler to the Amiga. With Commodities Exchange, any program function can be associated with key combinations or other input events ''globally'' allowing the creation utility programs that run in the background for all tasks.

== Custom Input Handlers ==

The input.device has a hand in almost all user input on the Amiga. It gathers input events from the keyboard, the gameport (mouse), and several other sources, into one input "stream". Special programs called input event handlers intercept input events along this stream, examining and sometimes changing the input events. Both Intuition and the console device use input handlers to process user input.

[[File:LibFig31-1.png|frame|center|The Amiga Input Stream]]

Using the input.device, a program can introduce its own custom handler into the chain of input handlers at almost any point in the chain. "Hot key" programs, shell pop-up programs, and screen blankers all commonly use custom input handlers to monitor user input before it gets to the Intuition input handler.

[[File:LibFig31-2.png|frame|center|A Custom Input Handler]]

Custom input handlers do have their drawbacks, however. Not only are these handlers hard to program, but because there is no standard way to implement and control them, multiple handlers often do not work well together. Their antisocial behavior can result in load order dependencies and incompatibilities between different custom input handlers. Even for the expert user, having several custom input handlers coexist peacefully can be next to impossible.

[[File:LibFig31-3.png|frame|center|The Commodities Network]]

Commodities Exchange eliminates these problems by providing a simple, standardized way to program and control custom input handlers. It is divided into two parts: an Exec library and a controller program.

The Exec library is called commodities.library. When it is first opened, commodities.library establishes a single input handler just before Intuition in the input chain. When this input handler receives an input event, it creates a CxMessage (Commodities Exchange Message) corresponding to the input event, and diverts the CxMessage through the network of Commodities Exchange input handlers.

These handlers are made up of trees of different CxObjects (Commodities Exchange Objects), each of which performs a simple operation on the CxMessages. Any CxMessages that exit the network are returned to the input.device's input stream as input events.

Through function calls to the commodities.library, an application can install a custom input handler. A Commodities Exchange application, sometimes simply referred to as a commodity, uses the CxObject primitives to do things such as filter certain CxMessages, translate CxMessages, signal a task when a CxObject receives a CxMessage, send a message when a CxObject receives a CxMessage, or if necessary, call a custom function when a CxObject receives a CxMessage.

=== Commodities Control ===

The standard controller program is called Exchange. It is located in the Utilities/Commodities drawer on your system partition. With Exchange, the user can monitor and control all the currently running Commodities Exchange applications from this one program. The user can enable and disable a commodity, kill a commodity, or, if the commodity has a window, ask the commodity to show or hide its window. When the user requests any of these actions, the controller program sends the commodity a message, telling it which action to perform.

Starting with version 53.4 of the commodities.library, functions are available that allow developers to write their own commodity control programs (Exchange replacements). These functions were not public previously.

=== Important Notes ===

* Commodities are special-purpose programs. In fact, most programs or applications are '''not''' suitable for becoming commodities. The Commodities Exchange framework is ideal for programs that need to monitor all user input: hotkey utilities, screen blankers, mouse blankers, etc.
* In the past, some developers turned their programs into commodities only to provide them with a handy keyboard shortcut to bring up/close their GUI. Please note that such practice is actually a misuse of the commodities framework.
* Commodities Exchange should never be used as an alternate method of receiving user input for an application. Other applications depend on getting user input in some form or another from the input stream. A greedy program that diverts input to itself rather than letting the input go to where the user expects it can seriously confuse the user, not to mention compromise the advantages of multitasking.

== CxObjects ==

CxObjects are the basic building blocks used to construct a commodity. A commodity uses CxObjects to take care of all manipulations of CxMessages. When a CxMessage "arrives" at a CxObject, that CxObject carries out its primitive action and then, if it has not deleted the CxMessage, it passes the CxMessage on to the next CxObject. A commodity links together CxObjects into a tree, organizing these simple action objects to perform some higher function.

A CxObject is in one of two states, active or inactive. An active CxObject performs its primitive action every time it receives a CxMessage. If a CxObject is inactive, CxMessages bypass it, continuing to the CxObject that follows the inactive one. By default, all CxObjects except the type called brokers are created in the active state.

Currently, there are seven types of CxObjects:

{| class="wikitable"
|+ Commodities Exchange Object Types
! Object Type
! Purpose
|-
| Broker || Registers a new commodity with the commodity network
|-
| Filter || Accepts or rejects input events based on criteria set up by the application
|-
| Sender || Sends a message to a message port
|-
| Translate || Replaces the input event with a different one
|-
| Signal || Signals a task
|-
| Custom || Calls a custom function provided by the commodity
|-
| Debug || Sends debug information out the serial port
|}

== Installing A Broker Object ==

The Commodities Exchange input handler maintains a master list of CxObjects to which it diverts input events using CxMessages. The CxObjects in this master list are a special type of CxObject called ''brokers''. The only thing a broker CxObject does is divert CxMessages to its own personal list of CxObjects. A commodity creates a broker and attaches other CxObjects to it. These attached objects take care of the actual input handler related work of the commodity and make up the broker's personal list.

The first program listing, "Broker.c", is a very simple example of a working commodity. It serves only to illustrate the basics of a commodity, not to actually perform any useful function. It shows how to set up a broker and process commands from the controller program.

Besides opening commodities.library and creating an Exec message port, setting up a commodity requires creating a broker. The function CxBroker() creates a broker and adds it to the master list.

<syntaxhighlight>
CxObj *CxBroker(struct NewBroker *nb, LONG *error);
</syntaxhighlight>

CxBroker()'s first argument is a pointer to a NewBroker structure:

<syntaxhighlight>
struct NewBroker {
BYTE nb_Version; /* There is an implicit pad byte after this BYTE */
BYTE *nb_Name;
BYTE *nb_Title;
BYTE *nb_Descr;
SHORT nb_Unique;
SHORT nb_Flags;
BYTE nb_Pri; /* There is an implicit pad byte after this BYTE */
struct MsgPort *nb_Port;
WORD nb_ReservedChannel; /* Unused, make zero for future compatibility */
};
</syntaxhighlight>

Commodities Exchange gets all the information it needs about the broker from this structure. NewBroker's nb_Version field contains the version number of the NewBroker structure. This should be set to NB_VERSION which is defined in <libraries/commodities.h>. The nb_Name, nb_Title, and nb_Descr point to strings which hold the name, title, and description of the broker. The two bit fields, nb_Unique and nb_Flags, toggle certain features of Commodities Exchange based on their values. They are discussed in detail later in this article.

The nb_Pri field contains the broker's priority. Commodities Exchange inserts the broker into the master list based on this number. Higher priority brokers get CxMessages before lower priority brokers.

CxBroker()'s second argument is a pointer to a LONG. If this pointer is not NULL, CxBroker() fills in this field with one of the following error return codes from <libraries/commodities.h>:

<syntaxhighlight>
CBERR_OK 0 /* No error */
CBERR_SYSERR 1 /* System error , no memory, etc */
CBERR_DUP 2 /* uniqueness violation */
CBERR_VERSION 3 /* didn't understand nb_VERSION */
</syntaxhighlight>

Once the broker object is created with CxBroker(), it must be activated with ActivateCxObject().

<syntaxhighlight>
LONG oldactivationvalue = ActivateCxObj(CxObj *co, LONG newactivationvalue);
</syntaxhighlight>

After successfully completing the initial set up and activating the broker, a commodity can begin its input processing loop waiting for CxMessages to arrive.

== CxMessages ==

There are actually two types of CxMessages. The first, CXM_IEVENT, corresponds to an input event and travels through the Commodities Exchange network. The other type, CXM_COMMAND, carries a command to a commodity. A CXM_COMMAND normally comes from the controller program and is used to pass user commands on to a commodity. A commodity receives these commands through an Exec message port that the commodity sets up before it calls CxBroker(). The NewBroker's nb_Port field points to this message port. A commodity can tell the difference between the two types of CxMessages by calling the CxMsgType() function.

<syntaxhighlight>
ULONG CxMsgType( CxMsg *cxm );
UBYTE *CxMsgData( CxMsg *cxm );
LONG CxMsgID ( CxMsg *cxm );
</syntaxhighlight>

A CxMessage not only has a type, it can also have a data pointer as well as an ID associated with it. The data associated with a CXM_IEVENT CxMessage is an InputEvent structure. By using the CxMsgData() function, a commodity can obtain a pointer to the corresponding InputEvent of a CXM_IEVENT message. Commodities Exchange gives an ID of zero to any CXM_IEVENT CxMessage that it introduces to the Commodities network but certain CxObjects can assign an ID to them.

For a CXM_COMMAND CxMessages, the data pointer is generally not used but the ID specifies a command passed to the commodity from the user operating the controller program. The CxMsgID() macro extracts the ID from a CxMessage.

=== A Simple Commodity Example ===

The example below, "Broker.c", receives input from one source, the controller program. The controller program sends a CxMessage each time the user clicks its Enable, Disable, or Kill gadgets. Using the CxMsgID() function, the commodity finds out what the command is and executes it.

<syntaxhighlight>
// broker.c - Simple skeletal example of opening a broker

#include <exec/libraries.h>
#include <libraries/commodities.h>
#include <dos/dos.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/commodities.h>

void ProcessMsg(void);

struct CommoditiesIFace *ICommodities = NULL;

CxObj *broker;
struct MsgPort *broker_mp;
ULONG cxsigflag;

struct NewBroker newbroker = {
NB_VERSION, /* nb_Version - Version of the NewBroker structure */
"Amiga broker", /* nb_Name - Name Commodities uses to identify this commodity */
"Broker", /* nb_Title - Title of commodity that appears in CXExchange */
"A simple example of a broker", /* nb_Descr - Description of the commodity */
0, /* nb_Unique - Tells CX not to launch another commodity with same name */
0, /* nb_Flags - Tells CX if this commodity has a window */
0, /* nb_Pri - This commodity's priority */
0, /* nb_Port - MsgPort CX talks to */
0 /* nb_ReservedChannel - reserved for later use */
};

int main()
{
CxMsg *msg;

struct Library *CxBase = = IExec->OpenLibrary("commodities.library", 50);
ICommodities = (struct CommoditiesIFace*)IExec->GetInterface(CxBase, "main", 1, NULL);
if (ICommodities != NULL)
{
/* Commodities talks to a Commodities application through */
/* an Exec Message port, which the application provides */
if (broker_mp = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END))
{
newbroker.nb_Port = broker_mp;

/* The commodities.library function CxBroker() adds a borker to the
* master list. It takes two arguments, a pointer to a NewBroker
* structure and a pointer to a LONG. The NewBroker structure contains
* information to set up the broker. If the second argument is not
* NULL, CxBroker will fill it in with an error code.
*/
if (broker = ICommodities->CxBroker(&newbroker, NULL))
{
cxsigflag = 1L << broker_mp->mp_SigBit;

/* After it's set up correctly, the broker has to be activated */
ICommodities->ActivateCxObj(broker, 1L);

/* the main processing loop */
ProcessMsg();

/* It's time to clean up. Start by removing the broker from the
* Commodities master list. The DeleteCxObjAll() function will
* take care of removing a CxObject and all those connected
* to it from the Commodities network
*/
ICommodities->DeleteCxObj(broker);

/* Empty the port of CxMsgs */
while(msg = (CxMsg *)IExec->GetMsg(broker_mp))
IExec->ReplyMsg((struct Message *)msg);
}
IExec->FreeSysObject(ASOT_PORT, broker_mp);
}
}

IExec->DropInterface((struct Interface*)ICommodities);
IExec->CloseLibrary(CxBase);

return 0;
}

void ProcessMsg(void)
{
CxMsg *msg;

uint32 sigrcvd, msgid, msgtype;
int32 returnvalue = 1;

while (returnvalue)
{
/* wait for something to happen */
sigrcvd = IExec->Wait(SIGBREAKF_CTRL_C | cxsigflag);

/* process any messages */
while(msg = (CxMsg *)IExec->GetMsg(broker_mp))
{
/* Extract necessary information from the CxMessage and return it */
msgid = ICommodities->CxMsgID(msg);
msgtype = ICommodities->CxMsgType(msg);
IExec->ReplyMsg((struct Message *)msg);

switch(msgtype)
{
case CXM_IEVENT:
/* Shouldn't get any of these in this example */
break;
case CXM_COMMAND:
/* Commodities has sent a command */
IDOS->Printf("A command: ");
switch(msgid)
{
case CXCMD_DISABLE:
IDOS->Printf("CXCMD_DISABLE\n");
/* The user clicked Commodities Exchange disable
* gadget better disable
*/
ICommodities->ActivateCxObj(broker, 0);
break;
case CXCMD_ENABLE:
/* user clicked enable gadget */
IDOS->Printf("CXCMD_ENABLE\n");
ICommodities->ActivateCxObj(broker, 1);
break;
case CXCMD_KILL:
/* user clicked kill gadget, better quit */
IDOS->Printf("CXCMD_KILL\n");
returnvalue = 0;
break;
}
break;
default:
IDOS->Printf("Unknown msgtype\n");
break;
}
}
/* Test to see if user tried to break */
if (sigrcvd & SIGBREAKF_CTRL_C)
{
returnvalue = 0;
IDOS->Printf("CTRL C signal break\n");
}
}
}
</syntaxhighlight>

Notice that "Broker.c" uses Ctrl-C as a break key. The break key for any commodity should be Ctrl-C.

=== Controller Commands ===

The commands that a commodity can receive from the controller program (as defined in <libraries/commodities.h>) are:

<syntaxhighlight>
CXCMD_DISABLE /* please disable yourself */
CXCMD_ENABLE /* please enable yourself */
CXCMD_KILL /* go away for good */
CXCMD_APPEAR /* open your window, if you can */
CXCMD_DISAPPEAR /* hide your window */
</syntaxhighlight>

The CXCMD_DISABLE, CXCMD_ENABLE, and CXCMD_KILL commands correspond to the similarly named controller program gadgets, Disable, Enable, and Kill; CXCMD_APPEAR and CXCMD_DISAPPEAR correspond to the controller program gadgets, Show and Hide. These gadgets are ghosted in Broker.c because it has no window (It doesn't make much sense to give the user a chance to click the Show and Hide gadgets). In order to do this, Broker.c has to tell Commodities Exchange to ghost these gadgets. When CxBroker() sets up a broker, it looks at the NewBroker.nb_Flags field to see if the COF_SHOW_HIDE bit (from <libraries/commodities.h>) is set. If it is, the "Show" and "Hide" gadgets for this broker will be selectable. Otherwise they are ghosted and disabled.

=== Shutting Down the Commodity ===

Shutting down a commodity is easy. After replying to all CxMessages waiting at the broker's message port, a commodity can delete its CxObjects. The DeleteCxObj() function removes a single CxObject from the Commodities network. DeleteCxObjectAll() removes multiple objects.

<syntaxhighlight>
VOID DeleteCxObj( CxObj *co );
VOID DeleteCxObjAll( CxObj *delete_co );
</syntaxhighlight>

If a commodity has a lot of CxObjects, deleting each individually can be a bit tedious. DeleteCxObjAll() will delete a CxObject and any other CxObjects that are attached to it. The HotKey.c example given later in this article uses this function to delete all its CxObjects. A commodity that uses DeleteCxObjAll() to delete all its CxObjects should make sure that they are all connected to the main one. (See the "Connecting CxObjects" section below.)

After deleting its CxObjects, a commodity must take care of any CxMessages that might have arrived at the message port just before the commodity deleted its objects.

<syntaxhighlight>
while(msg = (CxMsg *)IExec->GetMsg(broker_mp))
IExec->ReplyMsg((struct Message *)msg);
</syntaxhighlight>

== Commodity Tool Types ==

A goal of Commodities Exchange is to improve user control over input handlers. One way in which it accomplishes this goal is through the use of standard icon Tool Types. The user will expect commodities to recognize the set of standard Tool Types:

* CX_PRIORITY
* CX_POPUP
* CX_POPKEY

CX_PRIORITY lets the user set the priority of a commodity. The string "CX_PRIORITY=" is a number from -128 to 127. The higher the number, the higher the priority of the commodity, giving it access to input events before lower priority commodities. All commodities should recognize CX_PRIORITY.

CX_POPUP and CX_POPKEY are only relevant to commodities with a window. The string "CX_POPUP=" should be followed by a "yes" or "no", telling the commodity if it should or shouldn't show its window when it is first launched. CX_POPKEY is followed by a string describing the key to use as a hot key for making the commodity's window appear (pop up). The description string for CX_POPKEY describes an input event. The specific format of the string is discussed in the next section ("Filter Objects and the Input Description String").

=== Obsolete Parsing Functions ===

Prior to AmigaOS 4.0, the Commodities Library had the following support functions which were included in an external link library:

<syntaxhighlight>
UBYTE **ArgArrayInit(LONG argc, UBYTE **argv);
VOID ArgArrayDone(void);
STRPTR ArgString(UBYTE **tooltypearray, STRPTR tooltype, STRPTR defaultvalue);
LONG *ArgInt(UBYTE **tooltypearray, STRPTR tooltype, LONG defaultvalue);
</syntaxhighlight>

These functions are no longer available. Use IDOS->ReadArgs(), IIcon->FindToolType() and IIcon->MatchToolValue() instead, depending on whether the commodity was launched from Workbench or the Shell (CLI).

== Filter Objects and Input Description Strings ==

Because not all commodities are interested in every input event that makes it way down the input chain, Commodities Exchange has a method for filtering them. A filter CxObject compares the CxMessages it receives to a pattern. If a CxMessage matches the pattern, the filter diverts the CxMessage down its personal list of CxObjects.

<syntaxhighlight>
CxObj *CxFilter(STRPTR descriptionstring);
</syntaxhighlight>

The C macro CxFilter() (defined in <libraries/commodities.h>) returns a pointer to a filter CxObject. The macro has only one argument, a pointer to a string describing which input events to filter. The following regular expression outlines the format of the input event description string (CX_POPKEY uses the same description string format):

<pre>
[class] { [-] (qualifier | synonym) ) } [ [-] upstroke] [highmap | ANSICode]
</pre>

''Class'' can be any one of the class strings in the table below. Each class string corresponds to a class of input event as defined in <devices/inputevent.h>. Commodities Exchange will assume the class is rawkey if the class is not explicitly stated.

{| class="wikitable"
! Class String
! Input Event Class
|-
| "rawkey" || IECLASS_RAWKEY
|-
| "rawmouse" || IECLASS_RAWMOUSE
|-
| "event" || IECLASS_EVENT
|-
| "pointerpos" || IECLASS_POINTERPOS
|-
| "timer" || IECLASS_TIMER
|-
| "newprefs" || IECLASS_NEWPREFS
|-
| "diskremoved" || IECLASS_DISKREMOVED
|-
| "diskinserted" || IECLASS_DISKINSERTED
|}

''Qualifier'' is one of the qualifier strings from the table below. Each string corresponds to an input event qualifier as defined in <devices/inputevent.h>). A dash preceding the qualifier string tells the filter object not to care if that qualifier is present in the input event. Notice that there can be more than one qualifier (or none at all) in the input description string.

{| class="wikitable"
! Qualifier String
! Input Event Class
|-
| "lshift" || IEQUALIFIER_LSHIFT
|-
| "rshift" || IEQUALIFIER_RSHIFT
|-
| "capslock" || IEQUALIFIER_CAPSLOCK
|-
| "control" || IEQUALIFIER_CONTROL
|-
| "lalt" || IEQUALIFIER_LALT
|-
| "ralt" || IEQUALIFIER_RALT
|-
| "lcommand" || IEQUALIFIER_LCOMMAND
|-
| "rcommand" || IEQUALIFIER_RCOMMAND
|-
| "numericpad" || IEQUALIFIER_NUMERICPAD
|-
| "repeat" || IEQUALIFIER_REPEAT
|-
| "mouse_middlepress" || IEQUALIFIER_MIDBUTTON
|-
| "mouse_rightpress" || IEQUALIFIER_RBUTTON
|-
| "mouse_leftpress" || IEQUALIFIER_LEFTBUTTON
|-
| "relativemouse" || IEQUALIFIER_RELATIVEMOUSE
|}

''Synonym'' is one of the synonym strings from the table below. These strings act as synonyms for groups of qualifiers. Each string corresponds to a synonym identifier as defined in <libraries/commodities.h>. A dash preceding the synonym string tells the filter object not to care if that synonym is present in the input event. Notice that there can be more than one synonym (or none at all) in the input description string.

{| class="wikitable"
! Synonym String
! Synonym Identifier
! Description
|-
| "shift" || IXSYM_SHIFT || Look for either Shift key
|-
| "caps" || IXSYM_CAPS || Look for either Shift key or Caps Lock
|-
| "alt" || IXSYM_ALT || Look for either Alt key
|}

''Upstroke'' is the literal string "upstroke". If this string is absent, the filter considers only downstrokes. If it is present alone, the filter considers only upstrokes. If preceded by a dash, the filter considers both upstrokes and downstrokes.

''Highmap'' is one of the following strings:

"backspace", "del", "down", "enter", "esc", "f1", "f2",
"f3", "f4", "f5", "f6", "f7", "f8", "f9", "f10",
"f11, "f12", "help", "left", "return", "right", "space", "tab", "up".

''ANSICode'' is a single character (for example "a" that Commodities Exchange looks up in the system default keymap.

Here are some example description strings. For function key F2 with the left Shift and either Alt key pressed, the input description string would be:

<pre>
"rawkey lshift alt f2"
</pre>

To specify the key that produces an "a" (this may or may not be the A key depending on the keymap), with or without any Shift, Alt, or Control keys pressed use:

<pre>
"-shift -alt -control a"
</pre>

For a mouse move with the right mouse button down, use:

<pre>
"rawmouse mouse_rightpress"
</pre>

To specify a timer event use:

<pre>
"timer"
</pre>

== Connecting CxObjects ==

A CxObject has to be inserted into the Commodities network before it can process any CxMessages. AttachCxObj() adds a CxObject to the personal list of another CxObject. The HotKey.c example uses it to attach its filter to a broker.

<syntaxhighlight>
VOID AttachCxObj ( CxObj *headobj, CxObj *co);
VOID InsertCxObj ( CxObj *headobj, CxObj *co, CxObj *co_pred );
VOID EnqueueCxObj( CxObj *headobj, CxObj *co );
VOID SetCxObjPri ( CxObj *co, LONG pri );
VOID RemoveCxObj ( CxObj *co );
</syntaxhighlight>

AttachCxObj() adds the CxObject to the end of headobj's personal list. The ordering of a CxObject list determines which object gets CxMessages first. InsertCxObj() also inserts a CxObject, but it inserts it after another CxObject already in the personal list (co_pred in the prototype above).

Brokers aren't the only CxObjects with a priority. All CxObjects have a priority associated with them. To change the priority of any CxObject, use the SetCxObjPri() function. A commodity can use the priority to keep CxObjects in a personal list sorted by their priority. The commodities.library function EnqueueCxObj() inserts a CxObject into another CxObject's personal list based on priority.

Like its name implies, the RemoveCxObj() function removes a CxObject from a personal list. Note that it is not necessary to remove a CxObject from a list in order to delete it.

<syntaxhighlight>
/* HotKey.c - Simple hot key commodity
*/
#include <exec/libraries.h>
#include <libraries/commodities.h>
#include <dos/dos.h>

#include <proto/exec.h>
#include <proto/commodities.h>
#include <proto/icon.h>

#define EVT_HOTKEY 1L

void ProcessMsg(void);

struct CommoditiesIFace *ICommodities;
struct IconIFace *IIcon;

struct MsgPort *broker_mp;
CxObj *broker, *filter, *sender, *translate;

struct NewBroker newbroker = {
NB_VERSION,
"Amiga HotKey", /* string to identify this broker */
"A Simple HotKey",
"A simple hot key commodity",
NBU_UNIQUE | NBU_NOTIFY, /* Don't want any new commodities starting with this name. */
0, 0, 0, 0 /* If someone tries it, let me know */
};

uint32 cxsigflag;

int main(int argc, char **argv)
{
uint8 *hotkey, **ttypes;
CxMsg *msg;

struct Library *CxBase = IExec->OpenLibrary("commodities.library", 50);
ICommodities = (struct CommoditiesIFace*)IExec->GetInterface(CxBase, "main", 1, NULL);

/* open the icon.library for the support library */
/* functions, ArgArrayInit() and ArgArrayDone() */
struct Library *IconBase = IExec->OpenLibrary("icon.library", 50);
struct IconIFace *IIcon = (struct IconIFace*)IExec->GetInterface(IconBase, "main", 1, NULL);

if (ICommodities != NULL && IIcon != NULL)
{
if (broker_mp = CreateMsgPort())
{
newbroker.nb_Port = broker_mp;
cxsigflag = 1L << broker_mp->mp_SigBit;

/* ArgArrayInit() is a support library function (from the 2.0 version
* of amiga.lib) that makes it easy to read arguments from either a
* CLI or from Workbench's ToolTypes. Because it uses icon.library,
* the library has to be open before calling this function.
* ArgArrayDone() cleans up after this function.
*/
ttypes = ArgArrayInit(argc, argv);

/* ArgInt() (also from amiga.lib) searches through the array set up
* by ArgArrayInit() for a specific ToolType. If it finds one, it
* returns the numeric value of the number that followed the
* ToolType (i.e., CX_PRIORITY=7). If it doesn't find the ToolType,
* it returns the default value (the third argument)
*/
newbroker.nb_Pri = (int8)ArgInt(ttypes, "CX_PRIORITY", 0);

/* ArgString() works just like ArgInt(), except it returns a pointer to a string
* rather than an integer. In the example below, if there is no ToolType
* "HOTKEY", the function returns a pointer to "rawkey control esc".
*/
hotkey = ArgString(ttypes, "HOTKEY", "rawkey control esc");

if (broker = ICommodities->CxBroker(&newbroker, NULL))
{
/* CxFilter() is a macro that creates a filter CxObject. This filter
* passes input events that match the string pointed to by hotkey.
*/
if (filter = ICommodities->CxFilter(hotkey))
{
/* Add a CxObject to another's personal list */
ICommodities->AttachCxObj(broker, filter);

/* CxSender() creates a sender CxObject. Every time a sender gets
* a CxMessage, it sends a new CxMessage to the port pointed to in
* the first argument. CxSender()'s second argument will be the ID
* of any CxMessages the sender sends to the port. The data pointer
* associated with the CxMessage will point to a *COPY* of the
* InputEvent structure associated with the orginal CxMessage.
*/
if (sender = CxSender(broker_mp, EVT_HOTKEY))
{
ICommodities->AttachCxObj(filter, sender);

/* CxTranslate() creates a translate CxObject. When a translate
* CxObject gets a CxMessage, it deletes the original CxMessage
* and adds a new input event to the input.device's input stream
* after the Commodities input handler. CxTranslate's argument
* points to an InputEvent structure from which to create the new
* input event. In this example, the pointer is NULL, meaning no
* new event should be introduced, which causes any event that
* reaches this object to disappear from the input stream.
*/
if (translate = ICommodities->CxTranslate(NULL))
{
ICommodities->AttachCxObj(filter, translate);

/* CxObjError() is a commodities.library function that returns
* the internal accumulated error code of a CxObject.
*/
if (! CxObjError(filter))
{
ICommodities->ActivateCxObj(broker, 1L);
ProcessMsg();
}
}
}
}
/* DeleteCxObjAll() is a commodities.library function that not only
* deletes the CxObject pointed to in its argument, but it deletes
* all of the CxObjects that are attached to it.
*/
ICommodities->DeleteCxObjAll(broker);

/* Empty the port of all CxMsgs */
while(msg = (CxMsg *)IExec->GetMsg(broker_mp))
IExec->ReplyMsg((struct Message *)msg);
}
DeletePort(broker_mp);
}
/* this amiga.lib function cleans up after ArgArrayInit() */
ArgArrayDone();
}

IExec->DropInterface((struct Interface*)IIcon);
IExec->CloseLibrary(IconBase);

IExec->DropInterface((struct Interface*)ICommodities);
IExec->CloseLibrary(CxBase);

return 0;
}

void ProcessMsg(void)
{
extern struct MsgPort *broker_mp;
extern CxObj *broker;
extern ULONG cxsigflag;
CxMsg *msg;
uint32 sigrcvd, msgid, msgtype;
int32 returnvalue = 1;

while(returnvalue)
{
sigrcvd = IExec->Wait(SIGBREAKF_CTRL_C | cxsigflag);

while(msg = (CxMsg *)IExec->GetMsg(broker_mp))
{
msgid = ICommodities->CxMsgID(msg);
msgtype = ICommodities->CxMsgType(msg);
IExec->ReplyMsg((struct Message *)msg);

switch(msgtype)
{
case CXM_IEVENT:
IDOS->Printf("A CXM_EVENT, ");
switch(msgid)
{
case EVT_HOTKEY: /* We got the message from the sender CxObject */
IDOS->Printf("You hit the HotKey.\n");
break;
default:
IDOS->Printf("unknown.\n");
break;
}
break;
case CXM_COMMAND:
IDOS->Printf("A command: ");
switch(msgid)
{
case CXCMD_DISABLE:
IDOS->Printf("CXCMD_DISABLE\n");
ICommodities->ActivateCxObj(broker, 0L);
break;
case CXCMD_ENABLE:
IDOS->Printf("CXCMD_ENABLE\n");
ICommodities->ActivateCxObj(broker, 1L);
break;
case CXCMD_KILL:
IDOS->Printf("CXCMD_KILL\n");
returnvalue = 0;
break;
case CXCMD_UNIQUE:
/* Commodities Exchange can be told not only to refuse to launch a
* commodity with a name already in use but also can notify the
* already running commodity that it happened. It does this by
* sending a CXM_COMMAND with the ID set to CXMCMD_UNIQUE. If the
* user tries to run a windowless commodity that is already running,
* the user wants the commodity to shut down. */
IDOS->Printf("CXCMD_UNIQUE\n");
returnvalue = 0;
break;
default:
IDOS->Printf("Unknown msgid\n");
break;
}
break;
default:
IDOS->Printf("Unknown msgtype\n");
break;
}
}
if (sigrcvd & SIGBREAKF_CTRL_C)
{
returnvalue = 0;
IDOS->Printf("CTRL C signal break\n");
}
}
}
</syntaxhighlight>

== Sender CxObjects ==

A filter CxObject by itself is not especially useful. It needs some other CxObjects attached to it. A commodity interested in knowing if a specific key was pressed uses a filter to detect and divert the corresponding CxMessage down the filter's personal list. The filter does this without letting the commodity know what happened. The sender CxObject can be attached to a filter to notify a commodity that it received a CxMessage. CxSender() is a macro that creates a sender CxObject.

<syntaxhighlight>
senderCxObj = CxObj *CxSender(struct MsgPort *senderport, LONG cxmID);
</syntaxhighlight>

CxSender() supplies the sender with an Exec message port and an ID. For every CxMessage a sender receives, it sends a new CxMessage to the Exec message port passed in CxSender(). Normally, the commodity creates this port. It is not unusual for a commodity's broker and sender(s) to share an Exec message port. The HotKey.c example does this to avoid creating unnecessary message ports. A sender uses the ID (cxmID) passed to CxSender() as the ID for all the CxMessages that the it transmits. A commodity uses the ID to monitor CxMessages from several senders at a single message port.

A sender does several things when it receives a CxMessage. First, it duplicates the CxMessage's corresponding input event and creates a new CxMessage. Then, it points the new CxMessage's data field to the copy of the input event and sets the new CxMessage's ID to the ID passed to CxSender(). Finally, it sends the new CxMessage to the port passed to CxSender(), asynchronously.

Because HotKey uses only one message port between its broker and sender object, it has to extract the CxMessage's type so it can tell if it is a CXM_IEVENT or a CXM_COMMAND. If HotKey gets a CXM_IEVENT, it compares the CxMessage's ID to the sender's ID, EVT_HOTKEY, to see which sender sent the CxMessage. Of course HotKey has only one sender, so it only checks for only one ID. If it had more senders, HotKey would check for the ID of each of the other senders as well.

Although HotKey doesn't use it, a CXM_IEVENT CxMessage contains a pointer to the copy of an input event. A commodity can extract this pointer (using CxMsgData()) if it needs to examine the input event copy. This pointer is only valid before the CxMessage reply. Note that it does not make any sense to modify the input event copy.

Senders are attached almost exclusively to CxObjects that filter out most input events (usually a filter CxObject). Because a sender sends a CxMessage for every single input event it gets, it should only get a select few input events. The AttachCxObj() function can add a CxObject to the end of a filter's (or some other filtering CxObject's) personal list. A commodity should not attach a CxObject to a sender as a sender ignores any CxObjects in its personal list.

== Translate CxObjects ==

Normally, after a commodity processes a hot key input event, it needs to eliminate that input event. Other commodities may need to replace an input event with a different one. The translate CxObject can be used for these purposes.

<syntaxhighlight>
translateCxObj = CxObj *CxTranslate(struct InputEvent *newinputevent);
</syntaxhighlight>

The macro CxTranslate() creates a new translate CxObject. CxTranslate()'s only argument is a pointer to a chain of one or more InputEvent structures.

When a translate CxObject receives a CxMessage, it eliminates the CxMessage and its corresponding input event from the system. The translator introduces a new input event, which Commodities Exchange copies from the InputEvent structure passed to CxTranslate() (newinputevent from the function prototype above), in place of the deleted input event.

A translator is normally attached to some kind of filtering CxObject. If it wasn't, it would translate all input events into the same exact input event. Like the sender CxObject, a translator does not divert CxMessages down its personal list, so it doesn't serve any purpose to add any to it.

<syntaxhighlight>
VOID SetTranslate( CxObj *translator, struct InputEvent *ie );
</syntaxhighlight>

It is possible to change the InputEvent structure that a translator looks at when it creates and introduces new input events into the input stream. The function SetTranslate() accepts a pointer to the new InputEvent structure, which the translator will duplicate and introduce when it receives a CxMessage.

HotKey utilizes a special kind of translator. Instead of supplying a new input event, HotKey passes a NULL to CxTranslate(). If a translator has a NULL new input event pointer, it does not introduce a new input event, but still eliminates any CxMessages and corresponding input events it receives.

== CxObject Errors ==

A Commodities Exchange function that acts on a CxObject records errors in the CxObject's accumulated error field. The function CxObjError() returns a CxObject's error field.

<syntaxhighlight>
int32 co_errorfield = CxObjError( CxObj *co );
</syntaxhighlight>

Each bit in the error field corresponds to a specific type of error. The following is a list of the currently defined CxObject errors and their corresponding bit mask constants.

{| class="wikitable"
! Error Constant
! Meaning
|-
| COERR_ISNULL
| CxObjError() was passed a NULL.
|-
| COERR_NULLATTACH
| Someone tried to attach a NULL CxObject to this CxObject.
|-
| COERR_BADFILTER
| This filter CxObject currently has an invalid filter description.
|-
| COERR_BADTYPE
| Someone tried to perform a type specific function on the wrong type of CxObject (for example calling SetFilter() on a sender CxObject).
|}

The remaining bits are reserved for future use. HotKey.c checks the error field of its filter CxObject to make sure the filter is valid. HotKey.c does not need to check the other objects with CxObjError() because it already makes sure that these other objects are not NULL, which is the only other kind of error the other objects can cause in this situation.

Commodities Exchange has a function that clears a CxObject's accumulated error field, ClearCxObjError().

<syntaxhighlight>
VOID ClearCxObjError( CxObj *co );
</syntaxhighlight>

A commodity should be careful about using this, especially on a filter. If a commodity clears a filter's error field and the COERR_BADFILTER bit is set, Commodities Exchange will think that the filter is OK and start sending messages through it.

== Uniqueness ==

When a commodity opens its broker, it can ask Commodities Exchange not to launch another broker with the same name (nb_Name). The purpose of the uniqueness feature is to prevent the user from starting duplicate commodities. If a commodity asks, Commodities Exchange will not only refuse to create a new, similarly named broker, but it will also notify the original commodity if someone tries to do so.

A commodity tells Commodities Exchange not to allow duplicates by setting certain bits in the nb_Unique field of the NewBroker structure it sends to CxBroker():

{| class="wikitable"
| NBU_UNIQUE
| bit 0
|-
| NBU_NOTIFY
| bit 1
|}

Setting the NBU_UNIQUE bit prevents duplicate commodities. Setting the NBU_NOTIFY bit tells Commodities Exchange to notify a commodity if an attempt was made to launch a duplicate. Such a commodity will receive a CXM_COMMAND CxMessage with an ID of CXCMD_UNIQUE when someone tries to duplicate it. Because the uniqueness feature uses the name a programmer gives a commodity to differentiate it from other commodities, it is possible for completely different commodities to share the same name, preventing the two from coexisting. For this reason, a commodity should not use a name that is likely to be in use by other commodities (like "filter" or "hotkey"). Instead, use a name that matches the commodity name.

When "HotKey.c" gets a CXCMD_UNIQUE CxMessage, it shuts itself down. "HotKey.c" and all the windowless commodities that come with Workbench shut themselves down when they get a CXCMD_UNIQUE CxMessage. Because the user will expect all windowless commodities to work this way, all windowless commodities should follow this standard.

When the user tries to launch a duplicate of a system commodity that has a window, the system commodity moves its window to the front of the display, as if the user had clicked the "Show" gadget in the controller program's window. A windowed commodity should mimic conventions set by existing windowed system commodities, and move its window to the front of the display.

== Signal CxObjects ==

A commodity can use a sender CxObject to find out if a CxMessage has "visited" a CxObject, but this method unnecessarily uses system resources. A commodity that is only interested in knowing if such a visitation took place does not need to see a corresponding input event or a CxMessage ID. Instead, Commodities Exchange has a CxObject that uses an Exec signal.

<syntaxhighlight>
CxObj *signalCxObj = CxSignal(struct Task *, LONG cx_signal);
</syntaxhighlight>

CxSignal() sets up a signal CxObject. When a signal CxObject receives a CxMessage, it signals a task. The commodity is responsible for determining the proper task ID and allocating the signal. Normally, a commodity wants to be signaled so it uses FindTask(NULL) to find it's own task address. Note that cx_signal from the above prototype is the signal number as returned by AllocSignal(), not the signal mask made from that number. For more information on signals, see [[Exec_Signals|Exec Signals]].

The example "Divert.c" (shown a little later) uses a signal CxObject.

== Custom CxObjects ==

Although the CxObjects mentioned so far take care of most of the input event handling a commodity needs to do, they cannot do it all. This is why Commodities Exchange has a custom CxObject. When a custom CxObject receives a CxMessage, it calls a function provided by the commodity.

<syntaxhighlight>
CxObject *customCxObj = CxCustom(int32 *customfunction(), int32 cxmID);
</syntaxhighlight>

A custom CxObject is the only means by which a commodity can directly modify input events as they pass through the Commodities network as CxMessages. For this reason, it is probably the most dangerous of the CxObjects to use.

{{Note|title=A Warning About Custom CxObjects|text=Unlike the rest of the code a commodities programmer writes, the code passed to a custom CxObject runs as part of the input.device task, putting severe restrictions on the function. No DOS or Intuition functions can be called. No assumptions can be made about the values of registers upon entry. Any function passed to CxCustom() should be very quick and very simple, with a minimum of stack usage.}}

Commodities Exchange calls a custom CxObject's function as follows:

<syntaxhighlight>
VOID customfunction(CxMsg *cxm, CxObj *customcxobj);
</syntaxhighlight>

where cxm is a pointer to a CxMessage corresponding to a real input event, and customcxobj is a pointer to the custom CxObject. The custom function can extract the pointer to the input event by calling CxMsgData(). Before passing the CxMessage to the custom function, Commodities Exchange sets the CxMessage's ID to the ID passed to CxCustom().

The following is an example of a custom CxObject function that swaps the function of the left and right mouse buttons.

<syntaxhighlight>
custom = CxCustom(CxFunction, 0)

/* The custom function for the custom CxObject. Any code for a custom CxObj must be */
/* short and sweet. This code runs as part of the input.device task */
#define CODEMASK (0x00FF & IECODE_LBUTTON & IECODE_RBUTTON)

void CxFunction(register CxMsg *cxm, CxObj *co)
{
uint16 mousequals = 0x0000;

/* Get the struct InputEvent associated with this CxMsg. Unlike the InputEvent
* extracted from a CxSender's CxMsg, this is a *REAL* input event, be careful with it.
*/
struct InputEvent *ie = (struct InputEvent *)CxMsgData(cxm);

/* Check to see if this input event is a left or right mouse button */
/* by itself (a mouse button can also be a qualifier). If it is, flip the */
/* low order bit to switch leftbutton <--> rightbutton. */
if (ie->ie_Class == IECLASS_RAWMOUSE)
if ((ie->ie_Code & CODEMASK) == CODEMASK) ie->ie_Code ^= 0x0001;

/* Check the qualifiers. If a mouse button was down when this */
/* input event occurred, set the other mouse button bit. */
if (ie->ie_Qualifier & IEQUALIFIER_RBUTTON) mousequals |= IEQUALIFIER_LEFTBUTTON;
if (ie->ie_Qualifier & IEQUALIFIER_LEFTBUTTON) mousequals |= IEQUALIFIER_RBUTTON;

/* clear the RBUTTON and LEFTBUTTON qualifier bits */
ie->ie_Qualifier &= ~(IEQUALIFIER_LEFTBUTTON | IEQUALIFIER_RBUTTON);

/* set the mouse button qualifier bits to their new values */
ie->ie_Qualifier |= mousequals;
}
</syntaxhighlight>

== Debug CxObjects ==

The final CxObject is the debug CxObject. When a debug CxObject receives a CxMessage, it sends debugging information to the serial port using DebugPrintF().

<syntaxhighlight>
CxObj *debugCxObj = CxDebug(int32 ID);
</syntaxhighlight>

The debug CxObject will DebugPrintF() the following information about itself, the CxMsg, and the corresponding InputEvent structure:

<pre>
DEBUG NODE: 7CB5AB0, ID: 2
CxMsg: 7CA6EF2, type: 0, data 2007CA destination 6F1E07CB
dump IE: 7CA6F1E
Class 1
Code 40
Qualifier 8000
EventAddress 40001802
</pre>

There has to be a terminal connected to the Amiga's serial port to receive this information.

== The IX Structure ==

Commodities Exchange does not use the input event description strings discussed earlier to match input events. Instead, Commodities Exchange converts these strings to its own internal format. These input expressions are available for commodities to use instead of the input description strings. The following is the IX structure as defined in <libraries/commodities.h>:

<syntaxhighlight>
#define IX_VERSION 2

struct InputXpression {
UBYTE ix_Version; /* must be set to IX_VERSION */
UBYTE ix_Class; /* class must match exactly */
UWORD ix_Code;
UWORD ix_CodeMask; /* normally used for UPCODE */
UWORD ix_Qualifier;
UWORD ix_QualMask;
UWORD ix_QualSame; /* synonyms in qualifier */
};

typedef struct InputXpression IX;
</syntaxhighlight>

The ix_Version field contains the current version number of the InputXpression structure. The current version is defined as IX_VERSION. The ix_Class field contains the IECLASS_ constant (defined in <devices/inputevent.h>) of the class of input event sought. Commodities Exchange uses the ix_Code and ix_CodeMask fields to match the ie_Code field of a struct InputEvent. The bits of ix_CodeMask indicate which bits are relevant in the ix_Code field when trying to match against a ie_Code. If any bits in ix_CodeMask are off, Commodities Exchange does not consider the corresponding bit in ie_Code when trying to match input events. This is used primarily to mask out the IECODE_UP_PREFIX bit of rawkey events, making it easier to match both up and down presses of a particular key.

IX's qualifier fields, ix_Qualifier, ix_QualMask, and ix_QualSame, are used to match the ie_Qualifier field of an InputEvent structure. The ix_Qualifier and ix_QualMask fields work just like ix_Code and ix_CodeMask. The bits of ix_QualMask indicate which bits are relevant when comparing ix_Qualifier to ie_Qualifier. The ix_QualSame field tells Commodities Exchange that certain qualifiers are equivalent:

<syntaxhighlight>
#define IXSYM_SHIFT 1 /* left- and right- shift are equivalent */
#define IXSYM_CAPS 2 /* either shift or caps lock are equivalent */
#define IXSYM_ALT 4 /* left- and right- alt are equivalent */
</syntaxhighlight>

For example, the input description string

<pre>
"rawkey -caps -lalt -relativemouse -upstroke ralt tab"
</pre>

matches a tab upstroke or downstroke with the right Alt key pressed whether or not the left Alt, either Shift, or the Caps Lock keys are down. The following IX structure corresponds to that input description string:

<syntaxhighlight>
IX ix = {
IX_VERSION, /* The version */
IECLASS_RAWKEY, /* We're looking for a RAWKEY event */
0x42, /* The key the usa0 keymap maps to a tab*/
0x00FF & (~IECODE_UP_PREFIX), /* We want up and down key presses */
IEQUALIFIER_RALT, /* The right alt key must be down */
0xFFFF & ~(IEQUALIFIER_LALT | IEQUALIFIER_LSHIFT |
IEQUALIFIER_RSHIFT | IEQUALIFIER_CAPSLOCK | IEQUALIFIER_RELATIVEMOUSE),
/* don't care about left alt, shift, capslock, or relativemouse qualifiers */
IXSYM_CAPS /* The shift keys and the capslock key qualifiers are all equivalent */
};
</syntaxhighlight>

The CxFilter() macro only accepts a description string to describe an input event. A commodity can change this filter, however, with the SetFilter() and SetFilterIX() function calls.

<syntaxhighlight>
VOID SetFilter( CxObj *filter, STRPTR descrstring );
VOID SetFilterIX( CxObj *filter, IX *ix );
</syntaxhighlight>

SetFilter() and SetFilterIX() change which input events a filter CxObject diverts. SetFilter() accepts a pointer to an input description string. SetFilterIX() accepts a pointer to an IX input expression. A commodity that uses either of these functions should check the filter's error code with CxObjError() to make sure the change worked.

The function ParseIX() parses an input description string and translates it into an IX input expression.

<syntaxhighlight>
LONG errorcode = ParseIX( STRPTR descrstring, IX *ix );
</syntaxhighlight>

Commodities Exchange uses ParseIX() to convert the description string in CxFilter() to an IX input expression. As was mentioned previously, ParseIX() does not work with certain kinds of input strings.

== Controlling CxMessages ==

A Custom CxObject has the power to directly manipulate the CxMessages that travel around the Commodities network. One way is to directly change values in the corresponding input event. Another way is to redirect (or dispose of) the CxMessages.

<syntaxhighlight>
VOID DivertCxMsg ( CxMsg *cxm, CxObj *headobj, CxObj *retobj );
VOID RouteCxMsg ( CxMsg *cxm, CxObj *co );
VOID DisposeCxMsg( CxMsg *cxm );
</syntaxhighlight>

DivertCxMsg() and RouteCxMsg() dictate where the CxMessage will go next. Conceptually, DivertCxMsg() is analogous to a subroutine in a program; the CxMessage will travel down the personal list of a CxObject (headobj in the prototype) until it gets to the end of that list. It then returns and visits the CxObject that follows the return CxObject (the return CxObject in the prototype above is retobj). RouteCxMsg() is analogous to a goto in a program; it has no CxObject to return to.

DisposeCxMsg() removes a CxMessage from the network and releases its resources. The translate CxObject uses this function to remove a CxMessage.

The example "Divert.c" shows how to use DivertCxMsg() as well as a signal CxObject.

<pre>
;/* divert.c - commodity to monitor user inactivity - compiled with SASC 5.10
LC -b0 -cfist -v -j73 divert.c
Blink FROM LIB:c.o,divert.o TO divert LIBRARY LIB:LC.lib,LIB:Amiga.lib NODEBUG SC SD
quit; */
#include <exec/libraries.h>
#include <libraries/commodities.h>
#include <dos/dos.h>
#include <clib/exec_protos.h>
#include <clib/alib_protos.h>
#include <clib/alib_stdio_protos.h>
#include <clib/commodities_protos.h>
#include <devices/inputevent.h>

#ifdef LATTICE
int CXBRK(void) { return(0); } /* Disable Lattice CTRL/C handling */
int chkabort(void) { return(0); }
#endif

#define TIMER_CLICKS 100

void main(int, char **);
void ProcessMsg(void);
void CxFunction(CxMsg *, CxObj *);

struct Library *CxBase, *IconBase;
struct MsgPort *broker_mp;
CxObj *broker, *cocustom, *cosignal;

struct NewBroker newbroker =
{
NB_VERSION,
"Divert", /* string to identify this broker */
"Divert",
"show divert",
NBU_UNIQUE | NBU_NOTIFY, /* Don't want any new commodities starting with this name. */
0, 0, 0, 0 /* If someone tries it, let me know */
};

struct Task *task;
ULONG cxsigflag, signal, cxobjsignal;

void main(int argc, char **argv)
{
UBYTE **ttypes;
CxMsg *msg;

if (CxBase = OpenLibrary("commodities.library", 37L))
{
/* open the icon.library for support library functions, ArgArrayInit() and ArgArrayDone() */
if (IconBase = OpenLibrary("icon.library", 36L))
{
if (broker_mp = CreateMsgPort())
{
newbroker.nb_Port = broker_mp;
cxsigflag = 1L << broker_mp->mp_SigBit;

/* ArgArrayInit() is a support library function (in the 2.0 version of amiga.lib) */
/* that makes it easy to read arguments from either a CLI or from Workbench's */
/* ToolTypes. Because it uses icon.library, the library has to be open before */
/* before calling this function. ArgArrayDone() cleans up after this function. */
ttypes = ArgArrayInit(argc, argv);

/* ArgInt() (in amiga.lib) searches through the array set up by ArgArrayInit() */
/* for a specific ToolType. If it finds one, it returns the numeric value of the */
/* number that followed the ToolType (i.e., CX_PRIORITY=7). If it doesn't find */
/* the ToolType, it returns the default value (the third argument) */
newbroker.nb_Pri = (BYTE)ArgInt(ttypes, "CX_PRIORITY", 0);

if (broker = CxBroker(&newbroker, NULL))
{
/* CxCustom() takes two arguments, a pointer to the custom function */
/* and an ID. Commodities Exchange will assign that ID to any CxMsg */
/* passed to the custom function. */
if (cocustom = CxCustom(CxFunction, 0L))
{
AttachCxObj(broker, cocustom);

/* Allocate a signal bit for the signal CxObj */
if ( (signal = (ULONG)AllocSignal(-1L)) != -1)
{
/* set up the signal mask */
cxobjsignal = 1L << signal;
cxsigflag |= cxobjsignal;

/* CxSignal takes two arguments, a pointer to the task to signal */
/* (normally the commodity) and the number of the signal bit the */
/* commodity acquired to signal with. */
task = FindTask(NULL);
if (cosignal = CxSignal(task, signal))
{
AttachCxObj(cocustom, cosignal);
ActivateCxObj(broker, 1L);
ProcessMsg();
}
FreeSignal(signal);
}
}
/* DeleteCxObjAll() is a commodities.library function that not only deletes */
/* the CxObject pointed to in its argument, but it deletes all of the */
/* CxObjects that are attached to it. */
DeleteCxObjAll(broker);

/* Empty the port of all CxMsgs */
while(msg = (CxMsg *)GetMsg(broker_mp))
ReplyMsg((struct Message *)msg);
}
DeletePort(broker_mp);
}
ArgArrayDone(); /* this amiga.lib function cleans up after ArgArrayInit() */
CloseLibrary(IconBase);
}
CloseLibrary(CxBase);
}
}

void ProcessMsg(void)
{
extern struct MsgPort *broker_mp;
extern CxObj *broker;
extern ULONG cxsigflag;
CxMsg *msg;
ULONG sigrcvd, msgid;
LONG returnvalue = 1L;

while (returnvalue)
{
sigrcvd = Wait(SIGBREAKF_CTRL_C | cxsigflag);

while(msg = (CxMsg *)GetMsg(broker_mp))
{
msgid = CxMsgID(msg);
ReplyMsg((struct Message *)msg);

switch(msgid)
{
case CXCMD_DISABLE:
ActivateCxObj(broker, 0L);
break;
case CXCMD_ENABLE:
ActivateCxObj(broker, 1L);
break;
case CXCMD_KILL:
returnvalue = 0L;
break;
case CXCMD_UNIQUE:
returnvalue = 0L;
break;
}
}

if (sigrcvd & SIGBREAKF_CTRL_C) returnvalue = 0L;

/* Check to see if the signal CxObj signalled us. */
if (sigrcvd & cxobjsignal) printf("Got Signal\n");
}
}

/* The custom function for the custom CxObject. Any code for a custom CxObj must be short */
/* and sweet because it runs as part of the input.device task. */
void CxFunction(register CxMsg *cxm, CxObj *co)
{
struct InputEvent *ie;
static ULONG time = 0L;

/* Get the struct InputEvent associated with this CxMsg. Unlike the InputEvent */
/* extracted from a CxSender's CxMsg, this is a *REAL* input event, be careful with it. */
ie = (struct InputEvent *)CxMsgData(cxm);

/* This custom function counts the number of timer events that go by while no other input */
/* events occur. If it counts more than a certain amount of timer events, it clears the */
/* count and diverts the timer event CxMsg to the custom object's personal */
/* list. If an event besides a timer event passes by, the timer event count is reset. */
if (ie->ie_Class == IECLASS_TIMER)
{
time++;
if (time >= TIMER_CLICKS)
{
time = 0L;
DivertCxMsg(cxm, co, co);
}
}
else
time = 0L;
}
</pre>

== New Input Events ==

The Commodities Library also has functions used to introduce new input events to the input stream.

<syntaxhighlight>
struct InputEvent *InvertString( UBYTE *string, ULONG *keymap );
VOID FreeIEvents( struct InputEvent *ie );
VOID AddIEvents( struct InputEvent *ie );
</syntaxhighlight>

InvertString() is a function that accepts an ASCII string and creates a linked list of input events that translate into the string using the supplied keymap (or the system default if the key map is NULL). The NULL terminated string may contain ANSI character codes, an input description enclosed in angle (<>) brackets, or one of the following backslash escape characters:

{| class="wikitable"
| \r
| Return
|-
| \t
| Tab
|-
| \\
| Backslash
|}

For example:

<pre>
abc<alt f1>\rhi there.
</pre>

FreeIEvents() frees a list of input events allocated by InvertString(). AddIEvents() is a commodities.library function that adds a linked list of input events at the the top of the Commodities network. Each input event in the list is made into an individual CxMessage. Note that if passed a linked list of input events created by InvertString(), the order the events appear in the string will be reversed.

=== Example ===
<syntaxhighlight>
/* PopShell.c - Simple hot key commodity example.
Adapted by xenic from the original source code.

Compile commands: gcc PopShell.c -o popshell -lamiga -Wall

To run the compiled program - Open 2 shell windows. Execute
PopShell in the first shell window with a line like:
PopShell HOTKEY "ctrl alt f"
Activate the second shell window and enter the keyboard shortcut.
A new shell window should open on the Workbench screen.
*/

#include <stdio.h>
#include <signal.h>

#include <libraries/commodities.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/commodities.h>
#include <clib/alib_protos.h>

static CONST_STRPTR version USED = "$VER: PopShell 1.1 (05.11.2015)";
static CONST_STRPTR stackcookie USED = "$STACK: 32768";

#define EVT_HOTKEY 1L

struct Library *CxBase = NULL;
struct CommoditiesIFace *ICommodities = NULL;

struct MsgPort *broker_mp = NULL;
CxObj *broker, *filter;

struct NewBroker newbroker =
{
NB_VERSION,
"Amiga PopShell", /* string to identify this broker */
"A Simple PopShell",
"A simple PopShell commodity",
NBU_UNIQUE | NBU_NOTIFY, /* Don't want any new commodities starting with this name. */
0, 0, 0, 0 /* If someone tries it, let me know */
};

CONST_STRPTR newshell = "\rllehswen"; /* "newshell" spelled backwards */
struct InputEvent *ie = NULL;
uint32 cxsigflag;

#define TEMPLATE "HOTKEY/K,CX_PRIORITY/N"
enum
{
ARG_HOTKEY, ARG_PRIORITY, ARG_MAX
};

void ProcessMsg(void);

int main(int argc, char **argv)
{
STRPTR hotkey = NULL;
CxMsg *msg = NULL;
struct RDArgs *argsdata = NULL;
int32 rargs[ARG_MAX] = {0};
int8 priority = 0;

signal(SIGINT, SIG_IGN);

if ((CxBase = IExec->OpenLibrary("commodities.library", 37L)))
{
if ((ICommodities = (struct CommoditiesIFace *)IExec->GetInterface(CxBase, "main", 1, NULL)))
{
if ((argsdata = IDOS->ReadArgs(TEMPLATE, rargs, NULL)))
{
if (rargs[ARG_PRIORITY])
priority = (int8)*(uint32 *)rargs[ARG_PRIORITY];
if ((broker_mp = IExec->AllocSysObject(ASOT_PORT, NULL)))
{
newbroker.nb_Port = broker_mp;
cxsigflag = 1L << broker_mp->mp_SigBit;
newbroker.nb_Pri = priority;
hotkey = (STRPTR)rargs[ARG_HOTKEY];

if ((broker = ICommodities->CxBroker(&newbroker, NULL)))
{
/* CxFilter(), CxSender() & CxTranslate() are */
/* macros defined in libraries/commodities.h. */
/* CxFilter() creates a filter CxObject. */
/* CxSender() creates a sender CxObject. */
/* CxTranslate() creates a translation CxObject. */
if ((filter = CxFilter(hotkey)))
{
/* Add a filter CxObject to another's personal list. */
ICommodities->AttachCxObj(broker, filter);

/* Add a sender CxObject to the filter CxObject. */
ICommodities->AttachCxObj(filter, CxSender(broker_mp, EVT_HOTKEY));

/* Add a translation CxObject to the filter CxObject */
ICommodities->AttachCxObj(filter, CxTranslate(NULL));

if (!(ICommodities->CxObjError(filter)))
{
/* InvertString() is an amiga.lib function that creates a linked */
/* list of input events which would translate into the string */
/* passed to it. Note that it puts the input events in the */
/* opposite order in which the corresponding letters appear in */
/* the string. A translate CxObject expects them backwards. */
if ((ie = InvertString(newshell, NULL)))
{
ICommodities->ActivateCxObj(broker, 1L);
ProcessMsg();
/* we have to release the memory allocated by InvertString. */
FreeIEvents(ie);
}
}
}
/* DeleteCxObjAll() is a commodities.library function that */
/* deletes the CxObject pointed to in its argument and */
/* deletes all of the CxObjects attached to it. */
ICommodities->DeleteCxObjAll(broker);

/* Empty the port of all CxMsgs */
while((msg = (CxMsg *)IExec->GetMsg(broker_mp)))
IExec->ReplyMsg((struct Message *)msg);
}
IExec->FreeSysObject(ASOT_PORT, broker_mp);
}
IDOS->FreeArgs(argsdata); /* cleans up after ReadArgs() */
}
IExec->DropInterface((struct Interface *)ICommodities);
}
IExec->CloseLibrary(CxBase);
}
return RETURN_OK;
}

void ProcessMsg(void)
{
extern struct MsgPort *broker_mp;
extern CxObj *broker;
extern uint32 cxsigflag;
CxMsg *msg = NULL;
uint32 sigrcvd, msgid, msgtype;
int32 returnvalue = 1L;

while (returnvalue)
{
sigrcvd = IExec->Wait(SIGBREAKF_CTRL_C | cxsigflag);

while((msg = (CxMsg *)IExec->GetMsg(broker_mp)))
{
msgid = ICommodities->CxMsgID(msg);
msgtype = ICommodities->CxMsgType(msg);
IExec->ReplyMsg((struct Message *)msg);

switch(msgtype)
{
case CXM_IEVENT:
printf("A CXM_EVENT, ");
switch(msgid)
{
case EVT_HOTKEY:
/* We got the message from the sender CxObject */
printf("You hit the HotKey.\n");
/* Add the string "newshell" to input * stream. */
/* If a shell gets it, it'll open a new shell. */
ICommodities->AddIEvents(ie);
break;
default:
printf("unknown.\n");
break;
}
break;
case CXM_COMMAND:
printf("A command: ");
switch(msgid)
{
case CXCMD_DISABLE:
printf("CXCMD_DISABLE\n");
ICommodities->ActivateCxObj(broker, 0L);
break;
case CXCMD_ENABLE:
printf("CXCMD_ENABLE\n");
ICommodities->ActivateCxObj(broker, 1L);
break;
case CXCMD_KILL:
printf("CXCMD_KILL\n");
returnvalue = 0L;
break;
case CXCMD_UNIQUE:
/* Commodities Exchange can be told not only to refuse to launch a */
/* commodity with a name already in use but also can notify the */
/* already running commodity that it happened. It does this by */
/* sending a CXM_COMMAND with the ID set to CXMCMD_UNIQUE. If the */
/* user tries to run a windowless commodity that is already running, */
/* the user wants the commodity to shut down. */
printf("CXCMD_UNIQUE\n");
returnvalue = 0L;
break;
default:
printf("Unknown msgid\n");
break;
}
break;
default:
printf("Unknown msgtype\n");
break;
}
}

if (sigrcvd & SIGBREAKF_CTRL_C)
{
returnvalue = 0L;
printf("CTRL C signal break\n");
}
}
}
</syntaxhighlight>

== Function Reference ==

The following are brief descriptions of the Commodities Exchange functions covered in this article. See the SDK for details on each function call.

{| class="wikitable"
! Function
! Description
|-
| CxBroker()
| Creates a CxObject of type Broker.
|-
| CxFilter()
| Creates a CxObject of type Filter.
|-
| CxSender()
| Creates a CxObject of type Sender.
|-
| CxTranslate()
| Creates a CxObject of type Translate.
|-
| CxSignal()
| Creates a CxObject of type Signal.
|-
| CxCustom()
| Creates a CxObject of type Custom.
|-
| CxDebug()
| Creates a CxObject of type Debug.
|-
| DeleteCxObj()
| Frees a single CxObject
|-
| DeleteCxObjAll()
| Frees a group of connected CxObjects
|-
| ActivateCxObj()
| Activates a newly created CxObject in the commodities network.
|-
| CxTranslate()
| Sets up substitution of one input event for another by translate CxObjects.
|-
| CxMsgType()
| Finds the type of a CxMessage.
|-
| CxMsgData()
| Returns the CxMessage data.
|-
| CxMsgID()
| Returns the CxMessage ID.
|-
| CxObjError()
| Returns the CxObject's accumulated error field.
|-
| ClearCxObjError()
| Clear the CxObject's accumulated error field.
|-
| AttachCxObj()
| Attaches a CxObject to the end of a given CxObject's list.
|-
| InsertCxObj()
| Inserts a CxObject in a given position in a CxObject's list.
|-
| EnqueueCxObj()
| Inserts a CxObject in a CxObject's list by priority.
|-
| SetCxObjPri()
| Sets a CxObject's priority for EnqueueCxObj().
|-
| RemoveCxObj()
| Removes a CxObject from a list.
|-
| SetFilter()
| Set a filter for a CxObject from an input description string.
|-
| SetFilterIX()
| Set a filter for a CxObject from an IX data structure.
|-
| ParseIX()
| Convert an input description string to an IX data structure.
|-
| DivertCxMsg()
| Divert a CxMessage to one CxObject and return it to another.
|-
| RouteCxMsg()
| Redirect a CxMessage to a new CxObject.
|-
| DisposeCxMsg()
| Cancel a CxMessage removing it from the Commodities network.
|-
| InvertString()
| Creates a linked list of input events that correspond to a given string.
|-
| FreeIEvents()
| Frees the linked list of input events created with InvertString().
|-
| AddIEvents()
| Converts a list of input events to CxMessages and puts them into the network.
|-
| CopyBrokerList()
| Creates a local copy of the current broker list (V53.4).
|-
| FreeBrokerList()
| Frees the local broker list (V53.4).
|-
| BrokerCommand()
| Sends a command to a commodity broker (V53.4).
|}

=== Obsolete Functions ===

The following functions are obsolete and no longer used:

{| class="wikitable"
! Function
! Description
|-
| ArgArrayInit()
| Create a Tool Types array from argc and argv (Workbench or Shell).
|-
| ArgArrayDone()
| Free the resources used by ArgArrayInit().
|-
| ArgString()
| Return the string associated with a given Tool Type in the array.
|-
| ArgInt()
| Return the integer associated with a given Tool Type in the array.
|}

RealTime Library

2020-10-11T18:47:41Z

Frédéric Khannouf: /* Conductors and Playerlnfos */

The RealTime Library provides a convenient, higher-level interface to underlying hardware timers that is easy to use. The library also provides for the distribution of timing pulses to an unlimited number of client applications on a priority basis, thus supporting multitasking in the most robust manner possible.

= Conductors and PlayerInfos =

The RealTime Library uses the Conductor structure to manage timing. There can be any number of Conductor structures, each of which represents a separate and independent timing context (i.e. a group of applications that want to be synced together).

Each Conductor can have one or more client applications. A second structure called a PlayerInfo is set up by each client application that wants to get timing information from the Conductor. There is typically one Playerlnfo for each task that wants to get timing information (a task could have more than one but this would be unusual).

Both the Conductor and Playerlnfo structures are dynamic. You never create these structures by allocating and initializing them yourself. The system provides the functions to do this for you. Also, the structures are read-only. To change the fields within these structures, use the system-provided functions and tags.

An application will usually create a single PlayerInfo structure and then attach it to a Conductor. If the Conductor does not yet exist, it will be created by the system. To create a PlayerInfo structure you call CreatePlayerO:

<syntaxhighlight>
struct PlayerInfo *pi = IRealTime->CreatePlayer(Tag tag, ...);
</syntaxhighlight>

This call takes a list of tag items that describe the attributes of the Playerlnfo structure you want to create. (A complete list of all the tags available can be found in the Autodoc for SetPlayerAttrs().) It returns a pointer to the PlayerInfo. Here’s a fragment showing how to set up a PlayerInfo:

<syntaxhighlight>
struct PlayerInfo *pPlayerInfo = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
TAG_END);

if (pPlayerInfo != NULL )
{
// Your real-time application goes here...

IRealTime->DeletePlayer(pPlayerInfo);
}
</syntaxhighlight>

In the code above, a PlayerInfo will be created with the name of "My_player". It will be attached to the Conductor structure named "My_conductor". If a Conductor structure named "My_conductor" does not already exist, the system will create one. Other applications could also attach their PlayerInfos to "My_conductor".

When your application finishes, you should delete any PlayerInfos you have created by calling DeletePlayer(). The Conductor will be automatically deleted by the system (however, this won’t happen until '''all''' the PlayerInfos attached to a Conductor are deleted).

Once you have a PlayerInfo and Conductor set up, you can obtain timing pulses for your application. Timing pulses come from underlying timer chips and are passed to your application through the Conductor.

= Getting Clock Ticks =

The RealTime Library uses a tick frequency of 600 Hz so clock pulses are delivered approximately every 1.66 ms. There are two ways to get this timing information:

* An alarm's signal
* A clock tick callback hook

== Using the alarm facility ==

You can ask the RealTime Library to signal your task at some future time by using its alarm facility. This allows you to operate asynchronously. For instance, you could start a group of MIDI notes playing and set the realtime alarm to signal you when they should be stopped, then go on to some other job such as preparing the next group of notes before calling Wait() on the alarm signal.

The fragment below shows how to set up the library’s alarm clock to signal the calling task at time = 1000 ticks (the fragment assumes that the RealTime Library interface is already obtained).

<syntaxhighlight>
// This fragment assumes the that IRealTime is already obtained.
int8 midiSignal = IExec->AllocSignal(-1); // Allocate a wake-up signal bit
if (midiSignal != -1)
{
struct PlayerInfo *pPlayerInfo = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
PLAYER_SignalTask, IExec->FindTask(NULL),
PLAYER_AlarmSigBit, midiSignal,
TAG_END);

if (pPlayerInfo != NULL)
{
// Start the realtime clock running.
int32 res = IRealTime->SetConductorState(pPlayerInfo, CLOCKSTATE_RUNNING, 0);
if (!res)
{
BOOL timerr = IRealTime->SetPlayerAttrs(pPlayerInfo,
PLAYER_AlarmTime, 1000,
PLAYER_Ready, TRUE,
TAG_END);
if (timerr)
{
// You could do some other job before
// calling Wait() on the alarm signal.
IExec->Wait(1UL << midiSignal);
}
else IDOS->Print("Couldn't set alarm\n");
}
else IDOS->Printf("Couldn't start clock\n");
}
else IDOS->Printf("Couldn't set up PlayerInfo structure.\n");
}
else IDOS->Printf("Couldn't allocate signal.\n");
</syntaxhighlight>

In the fragment above, the calling task requests a PlayerInfo with an alarm clock feature by passing the PLAYER_AlarmSigBit tag to CreatePlayer() The ti_Data field of this tag contains the signal bit that will be set by the RealTime Library when the alarm goes off. The PLAYER_SignalTask tag indicates which task will be signaled.

The realtime clock is then started by calling SetConductorState() (discussed below). This is important since any alarm requests made when the clock is stopped will be ignored.

Finally, the alarm time is set by calling SetPlayerAttrs(). The parameters to this call are:
<syntaxhighlight>
BOOL result = SetPlayerAttrs(struct PlayerInfo *pi, Tag tag, ...);
</syntaxhighlight>

The pi parameter indicates which Playerlnfo structure is to have its attributes changed. The Tag items indicate the attributes and their new values. If the change is made successfully, then TRUE is returned. FALSE indicates failure. In the fragment above, a wake-up time is
requested using the PLAYER_A1armTime tag. Also, the calling task indicates to the Conductor that it is ready by using the PLAYER_Ready tag (more on this below).

At this point, the call to Wait(1UL << midiSignal) causes the task to sleep until time = 1000 ticks.

== Using the clock tick callback facility ==

The discussion so far has concentrated on the alarm facility of the RealTime Library. An even finer level of control over time is available using the clock tick callback hook facility. Instead of setting an alarm to signal your task at some future time, the hook facilities allow your application code to be invoked whenever Conductor time is updated.

The realtime clock is driven by an interrupt that simply increments the base time and then uses software interrupts to distribute the time to any Conductors. By using a callback hook, you can have your custom code invoked at the software interrupt level (before tasks)
whenever Conductor time is refreshed.

To set up a callback hook, you use the PLAYER_Hook tag with the address of a standard Hook structure as defined in <utilities/hook.h>. This structure contains the address of the code you want to be invoked whenever the RealTime Library updates your Conductor. Here’s a code fragment showing how this is done:

<syntaxhighlight>
struct Task *My_task;
int8 My_signal;

uint32 My_hookFunc(struct Hook *hook, struct pmTime *msg, struct PlayerInfo *pi);

int main()
{
// ...Open the RealTime Library and do other set up here...

struct Hook My_hook;
My_hook.h_Entry = (HOOKFUNC)My_hookFunc;

uint32 ticks = 1000;
stuct PlayerInfo *pPlayerInfo = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
PLAYER_Hook, &My_hook,
PLAYER_UserData, &ticks,
TAG_END);

if (pPlayerInfo != NULL)
{
My_task = IExec->FindTask(NULL); // Initialize these globals so that
My_signal = IExec->AllocSignal(-1); // the hook function can signal us.
if (My_signal != -1)
{
// Start the clock running.
int32 res = IRealTime->SetConductorState(pPlayerInfo, CLOCKSTATE_RUNNING, 0);
if (!res)
{
// ...your code goes here...
IExec->Wait(1UL << My_signal | SIGBREAKF_CTRL_C);
}

IExec->FreeSignal(My_signal);
}

IRealTime->DeletePlayer(pPlayerInfo);
}

// ...Close the library, etc...
}
</syntaxhighlight>

In the code above the function named My_hookFunc() will be called by the RealTime Library whenever it updates Conductor time.

Here’s the callback hook function itself. This simply compares Conductor time to a variable, ticks, whose address is pointed to by pi>pi_UserData. Notice how this address was filled in using the PLAYER_UserData tag in the call to SetPlayerAttrs() in main() above. When
Conductor time equals or exceeds ticks, the hook function signals the main task.

<syntaxhighlight>
// Hook code called whenever the RealTime Library updates Conductor time.
// Normally this is 600 times/sec.
uint32 My_hookFunc(struct Hook *hook, struct pmTime *msg, struct PlayerInfo *pi)
{
switch (msg->pmt_Method)
{
case PM_TICK:
// Test whether Conductor time has exceeded the number in *ticks*.
// If it has, then signal the parent task.
if ((*uint32*)(pi->pi_Userdata)) < pi->pi_Source->cdt_ClockTime)
IExec->Signal(My_task, 1UL << My_signal);
break;

default:
break;
}

return 0;
}
</syntaxhighlight>

= More About Conductors =

It is the job of the Conductor to act as middleman between the Amiga's timing hardware and client tasks represented by PlayerInfo structures. Each Conductor keeps track of:
* an Exec list of all its client players
* the state of the conductor (i.e. running, stopped, paused, locating)
* what time it is relative to start time
* whether the Conductor is using the Amiga’s internal hardware for its timing pulses or an external source

As shown in the examples above, the "state" of the Conductor can be changed at any time by calling SetConductorState(). If the call succeeds, zero is returned:

<syntaxhighlight>
int32 res = IRealTime->SetConductorState(struct Playerlnfo *pi, int32 newstate, int32 ti);
</syntaxhighlight>

The pi parameter is a pointer to a PlayerInfo structure that is linked to the Conductor you want to change. The ti parameter is a time offset used for special cases (typically set to zero). The ''newstate'' parameter is one of the following:
{| class="wikitable"
| CLOCKSTATE_STOPPED || The clock is not running
|-
| CLOCKSTATE_PAUSED || To the RealTime Library, this is exactly the same as stopped. This is provided as a convenience to those applications that wish to make a distinction between the two.
|-
| CLOCKSTATE_RUNNING || The clock is running and time pulses are being distributed to any client applications (Playerlnfos) that are ready.
|-
| CLOCKSTATE_LOCATE || This is the same as running with one exception: the clock docs not actually start until ''all'' client applications have indicated that they are ready by setting the PLAYER_Ready attribute of their PlayerInfo to TRUE. This allows applications that cannot start immediately to set up before timing pulses actually begin.
|}

The difference between locating and running requires some explanation. Each Playerlnfo has a "ready bit" which is used to tell the RealTime Library that the player is ready to receive ticks. This bit is reset each time the library relocates the clock to a new time.

The reason for the ready bit is that some applications need to find the appropriate location in the multimedia sequence or score before they can start playing at the new location. In some cases this can take a considerable amount of time. Hence, CLOCKSTATE__LOCATE is used with the ready bit to allow all players that are sharing a timing context to be synchronized together.

Players can set the state of their ready bit by using the PLAYER_Ready tag attribute either when the Playerlnfo is created with CreatePlayer() or later with SetPlayerAttrs(). See the first code fragment above for an example of this.

Newlib Library

2020-07-05T13:34:41Z

Frédéric Khannouf: Small correction in the last Shared Interface Pointer sentence.

The built-in AmigaOS C library is a variant of the [http://sourceware.org/newlib/ Newlib C standard library] implementation. This section describes features of Newlib which are unique to AmigaOS.

== Shared Interface Pointer ==

Newlib is a rather unique in that it uses a shared interface pointer name INewlib (struct Interface* type). This is only a concern when you are not using the standard C startup code and opening newlib.library directly. One consequence of using a shared interface pointer is that you must specify the NP_Child tag when using IDOS->CreateNewProc() if your child process is going to share the parent process' newlib context information (e.g. stdin, stdout and stderr).

== Startup Code ==

The standard C startup code provides information on whether your application was launched from Workbench, Shell console or as a file system. Your program always starts using the standard '''argc''' and '''argv''' parameters but they are interpreted differently depending on how it was started.

<syntaxhighlight>
int main(int argc, char **argv)
</syntaxhighlight>

=== Workbench ===

The '''argc''' argument is equal to zero. The '''argv''' argument is a pointer to a struct WBStartup.

<syntaxhighlight>
#include <workbench/startup.h>

int main(int argc, char **argv)
{
struct WBStartup *wbstartup;

if (argc == 0)
{
wbstartup = (struct WBStartup*)argv;
// Parse wbstartup and enter main processing loop.
...
}

return 0;
}
</syntaxhighlight>

=== Shell ===

If '''argc''' is greater than zero then it means the application was started from the Shell console and the normal C startup rules apply.

<syntaxhighlight>
int main(int argc, char **argv)
{
if (argc > 0)
{
// Parse argv and enter main processing loop.
...
}

return 0;
}
</syntaxhighlight>

=== File System ===

If '''argc''' is -1 then means the application was started as a file system. This special option should only be used by file systems.

<syntaxhighlight>
#include <dos/dosextens.h>

int main(int argc, char **argv)
{
int result;

if (argc == -1)
{
struct DosPacket *pkt = (struct DosPacket*)argv;
struct Message *msg = pkt->dp_Link;

// File system initialization.
BOOL initialized = file_system_init(msg);

if (initialized)
{
// Reply to the startup packet before entering main loop.
pkt->dp_Res1 = DOSTRUE;
pkt->dp_Res2 = 0;
IExec->PutMsg(pkt->dp_Port, msg);

// File system main loop.
...

result = RETURN_OK;
}
else
{
// File system failed to initialize so return a DOS error code.
pkt->dp_Res1 = DOSFALSE;
pkt->dp_Res2 = ERROR_NO_FREE_STORE;
IExec->PutMsg(pkt->dp_Port, msg);

result = RETURN_FAIL;
}
}

return result;
}
</syntaxhighlight>

=== Standard Interfaces ===

The following interfaces are handled by the C startup code and are guaranteed to be present when main() is called:
* IExec
* IDOS
* IUtility

=== Options ===

<syntaxhighlight>
extern const char *__stdiowin;
</syntaxhighlight>

Define '''__stdiowin''' to control the default standard I/O window which will open automatically if your program needs it. The default is "CON:64/48/800/200/[CLI command name|Task name]/AUTO/CLOSE/WAIT".

<syntaxhighlight>
extern int __unix_path_semantics;
</syntaxhighlight>
Define to 1 to enable POSIX style path semantics which is useful when porting applications from UNIX.

== DOS File Handles ==

Sometimes the underlying DOS file handle may be required in some special circumstances. The '''_get_osfhandle()''' function is provided in the '''fcntl.h''' header file to access DOS file handles.

The following is an example program which demonstrates the feature.
<syntaxhighlight>
#include <proto/dos.h>
#include <stdio.h>
#include <fcntl.h>

int main()
{
printf("0x%08x 0x%08x 0x%08x\n",
(unsigned int)IDOS->Input(),
(unsigned int)IDOS->Output(),
(unsigned int)IDOS->ErrorOutput());

printf("0x%08x 0x%08x 0x%08x\n",
_get_osfhandle( fileno(stdin) ),
_get_osfhandle( fileno(stdout) ),
_get_osfhandle( fileno(stderr) ));

return 0;
}
</syntaxhighlight>

Note that this feature is available in newlib.library 53.20 and higher.

Keymap Library

2019-08-18T15:54:50Z

Frédéric Khannouf: Fixed small typos in MapRawKey.c preventing accurate value to be printed to the console

{{WIP}}
== Keymap Library ==

Amiga computers are sold internationally with a variety of local keyboards which match the standards of particular countries. All Amigas have keyboards which are physically similar, and keys which output the same low-level raw key code for any particular physical key. However, in different countries, the keycaps of the keys may contain different letters or symbols. Since the physical position of a key determines the raw key code that it generates, raw key codes are not internationally compatible. For instance, on the German keyboard, the Y and Z keys are swapped when compared to the USA keyboard. The second key on the fifth row will generate the same raw key code on all Amiga keyboards, but should be decoded as a Z on a US keyboard and as a Y on a German keyboard.

The Amiga uses the [http://www.ecma-international.org/publications/standards/Ecma-094.htm ECMA-94 Latin 1 International 8-bit] character set, and can map raw key codes to any desired ANSI character value, string, or escape sequence. This allows national keyboards to be supported by using keymaps. A keymap is a file which describes what character or string is tied to what key code. Generally, the user's startup-sequence will set a system default keymap that is correct for the user's keyboard. The console.device translates the raw key codes into the correct characters based on the installed keymap. This includes the translation of special deadkey sequential key combinations to produce accented international characters.

Programs which perform keyboard input using the console.device, CON:, RAW:, or Intuition VANILLAKEY, will receive custom keymaps, or may need to perform their own translation between raw key codes and ANSI characters. In this article, the term ANSI refers to the standard 8-bit character definitions which include printable ASCII characters, special characters, and escape sequences.

Keymap.library offers some of the keymap commands of the console.device, enabling applications to inquire after the default keymap and map key codes to ANSI characters. It also provides the ability to map ANSI characters back into raw codes. Unlike the console.device however, it can not be used to select a keymap for only one application, i.e., one console window.

As a prelude to the following material, note that the Amiga keyboard transmits raw key information to the computer in the form of a key position and a transition. Raw key positions range from hexadecimal 00 to 7F. When a key is released, its raw key position, plus hexadecimal 80, is transmitted.

== Keymap Functions ==

{| class="wikitable"
|+Keymap Library Functions
|-
|AskKeyMapDefault()
|Ask for a pointer to the current default keymap
|-
|MapANSI()
|Encode an ANSI string into key codes
|-
|MapRawKey()
|Decode a raw key input event to an ANSI string
|-
|SetKeyMapDefault()
|Set the current default keymap
|}

{| class="wikitable"
|+Console Device Keymap Commands
|-
|CD_ASKKEYMAP
|Ask for the current console's keymap
|-
|CD_SETKEYMAP
|Set the current console's keymap
|-
|CD_ASKDEFAULTKEYMAP*
|Set the current default keymap
|-
|CD_SETDEFAULTKEYMAP**
|Ask for a pointer to the current default keymap
|-
|colspan="2"|* Obsolete - use AskKeyMapDefault()
|-
|colspan="2"|** Obsolete - use SetKeyMapDefault()
|}

All of these commands deal with a set of pointers to key translation arrays, known as the KeyMap structure. The KeyMap structure is defined in <devices/keymap.h> and is shown below.

<syntaxhighlight>
struct KeyMap
{
UBYTE *km_LoKeyMapTypes;
ULONG *km_LoKeyMap;
UBYTE *km_LoCapsable;
UBYTE *km_LoRepeatable;
UBYTE *km_HiKeyMapTypes;
ULONG *km_HiKeyMap;
UBYTE *km_HiCapsable;
UBYTE *km_HiRepeatable;
};
</syntaxhighlight>

The KeyMap structure contains pointers to arrays which define the ANSI character or string that should be produced when a key or a combination of keys are pressed. For example, a keymap might specify that the key with raw value hex 20 should produce the ANSI character "a", and if the Shift key is being held it should produce the character "A".

=== Asking for the Default Keymap ===

The '''AskKeyMapDefault()''' returns a pointer to the current default keymap. To use the mapping functions in keymap.library it is normally not necessary to call this function. They accept NULL as equivalent to 'use default keymap' and will call this function for you. You can use this pointer for example to cache the system default in order to temporarily change the keymap your applications uses, or find the keymap in the keymap.resource list of loaded keymaps. You should never change the system wide default keymap unless the user asks you to do so; since the Amiga is a multitasking system, changing the keymap could interfere with the behaviour of other applications.

=== Setting the Default Keymap ===

The system default keymap can be set with the '''SetKeyMapDefault()''' function. This function takes a pointer to a loaded keymap.
In general, this function should never be used by an application unless the application is a system Preferences editor, or an
application that takes over the system. Normal applications should instead attach a console.device unit to their own Intuition window (see the ''Devices'' volume), and use the console.device command '''CD_SETKEYMAP''' to set a keymap only for their own console.

When making a keymap the system default, first check whether the keymap has been loaded previously by checking the keymap list of the keymap.resource. If it has not been loaded already, it can be loaded from DEVS:Keymaps, and added to the keymap list of keymap.resource. This will ensure that other applications which may want the keymap will not have to load a second instance. Once made the default, the keymap can never be safely removed from memory, even after if it is no longer the default, since other applications may still have and use a pointer to it.

=== Accessing the Keymap for the Current Console ===

The function '''AskKeyMap()''' shown below does not return a pointer to a table of pointers to currently assigned key mapping. Instead, it ''copies'' the current set of pointers to a user-designated area of memory. '''AskKeyMap()''' returns a TRUE or FALSE value that says whether or not the function succeeded.

The function '''SetKeyMap()''', also shown below, copies the designated key map data structure to the console device. Thus this routine is complementary to '''AskKeymap()''' in that it can restore an original key mapping as well as establish a new one.

{{Note|title=Ask/SetKeyMap()|text=These functions assume that you have already opened the ''console.device'' and that ''request'' is a valid IOStdReq structure for the newly opened console. These functions are not part of the keymap.library, nor of the console.device. These merely demonstrate '''CD_ASKKEYMAP''' and '''CD_SETKEYMAP''' which are console.device commands.}}

<syntaxhighlight>
/* These functions require that you have created a port and an IO request,
* and have opened the console device as shown in the "Console Device" section.
*/
#include <devices/keymap.h>

BOOL AskKeyMap(struct IOStdReq *request, struct KeyMap *keymap)
{
request->io_Command = CD_ASKKEYMAP;
request->io_Length = sizeof(struct KeyMap);
request->io_Data = (APTR)keymap; /* where to put it */
IExec->DoIO(request);
if(request->io_Error) return(FALSE);
else return(TRUE); /* if no error, it worked. */
}

BOOL SetKeyMap(struct IOStdReq *request, struct KeyMap *keymap)
{
request->io_Command = CD_SETKEYMAP;
request->io_Length = sizeof(struct KeyMap);
request->io_Data = (APTR)keymap; /* where to get it */
IExec->DoIO(request);
if(request->io_Error) return(FALSE);
else return(TRUE); /* if no error, it worked. */
}
</syntaxhighlight>

=== Mapping Key Codes to ANSI Strings ===

'''MapRawKey()''' converts raw key codes in ANSI characters based on a default or supplied keymap.

<syntaxhighlight>
WORD MapRawKey(struct InputEvent *inputevent, STRPTR buffer, WORD bufferlength, struct Keymap *keymap);
</syntaxhighlight>

'''MapRawKey()''' takes an IECLASS_RAWKEY inputevent, which may be chained, and converts the key codes to ANSI characters which are placed in the specified buffer. If the buffer would overflow, for example because a longer string is attached to a key, -1 will be returned. If no error occured, '''MapRawKey()''' will return the number of bytes written in the buffer. The keymap argument can be set to NULL if the default keymap is to be used for translation, or can be a pointer to a specific '''KeyMap''' structure.

The following example shows how to implement the '''MapRawKey()''' function.

<syntaxhighlight>
/*
* maprawkey.c - Map Intuition RAWKEY events to ANSI with MapRawKey();
*/
#include <exec/types.h>
#include <exec/memory.h>
#include <dos/dos.h>
#include <intuition/intuition.h>
#include <devices/inputevent.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/keymap.h>
#include <proto/intuition.h>

/* our function prototypes */
void openall(void);
void closeall(void);
void closeout(UBYTE *errstring, LONG rc);

struct Library *IntuitionBase = NULL;
struct IntuitionIFace *IIntuition = NULL;

struct Library *KeymapBase = NULL;
struct KeymapIFace *IKeymap = NULL;

struct Window *window = NULL;

int main(int argc, char **argv)
{
struct IntuiMessage *imsg;
APTR *eventptr;
struct InputEvent inputevent = {0};
LONG windowsignal;
UBYTE buffer[8];
COUNT i;
BOOL Done = FALSE;

openall();

window = IIntuition->OpenWindowTags(NULL,
WA_Width, 500,
WA_Height, 60,
WA_Title, "MapRawKey - Press Keys",
WA_Flags, WFLG_CLOSEGADGET | WFLG_ACTIVATE,
WA_IDCMP, IDCMP_RAWKEY | IDCMP_CLOSEWINDOW,
TAG_END);
if(window == NULL) closeout("Can't open window",RETURN_FAIL);

windowsignal = 1L << window->UserPort->mp_SigBit;

/* Initialize InputEvent structure (already cleared to 0) */
inputevent.ie_Class = IECLASS_RAWKEY;

while(!Done)
{
IExec->Wait(windowsignal);

while (imsg = (struct IntuiMessage *)IExec->GetMsg(window->UserPort))
{
switch(imsg->Class)
{
case IDCMP_CLOSEWINDOW:
Done = TRUE;
break;

case IDCMP_RAWKEY:
inputevent.ie_Code = imsg->Code;
inputevent.ie_Qualifier = imsg->Qualifier;

IDOS->Printf("RAWKEY: Code=$%04lx Qualifier=$%04lx\n",
imsg->Code, imsg->Qualifier);

/* Make sure deadkeys and qualifiers are taken
* into account.
*/
eventptr = imsg->IAddress;
inputevent.ie_EventAddress = *eventptr;

/* Map RAWKEY to ANSI */
i = IKeymap->MapRawKey(&inputevent, buffer, 8, NULL);

if (i == -1) IDOS->Write(IDOS->Output(),"*Overflow*",10);
else if (i)
{
/* This key or key combination mapped to something */
IDOS->Printf("MAPS TO: ");
IDOS->Write(IDOS->Output(),buffer,i);
IDOS->Printf("\en");
}
break;
}
IExec->ReplyMsg((struct Message *)imsg);
}
}
IIntuition->CloseWindow(window);
closeall();
return RETURN_OK;
}

void openall(void)
{
KeymapBase = IExec->OpenLibrary("keymap.library", 50);
IKeymap = (struct KeymapIFace*)IExec->GetInterface(KeymapBase, "main", 1, NULL);
if (IKeymap == NULL) closeout("Can't get IKeymap",RETURN_FAIL);

IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);
if (IIntuition == NULL) closeout("Can't get IIntuition",RETURN_FAIL);
}

void closeall(void)
{
IExec->DropInterface((struct Interface*)IIntuition);
IExec->CloseLibrary(IntuitionBase);

IExec->DropInterface((struct Interface*)IKeymap);
IExec->CloseLibrary(KeymapBase);
}

void closeout(UBYTE *errstring, LONG rc)
{
if (*errstring) IDOS->Printf("%s\en",errstring);
closeall();
exit(rc);
}
</syntaxhighlight>

=== Mapping ANSI Strings to Key Codes ===

The '''MapANSI()''' function translates ANSI strings into raw key codes, complete with qualifiers and (double) dead keys, based on a default or supplied keymap.

<syntaxhighlight>
LONG MapANSI(UBYTE *string, LONG stringlength, UBYTE *buffer, LONG bufferlength, struct KeyMap *keymap);
</syntaxhighlight>

The string argument is a pointer to an ANSI string, of length stringlength. The buffer argument is a pointer to the memory block where the translated key codes will be placed. The length of this buffer must be indicated in WORDs since each translation will occupy one byte for the key code and one for the qualifier. Since one ANSI character can be translated to two dead keys and one key, the buffer must be at least 3 WORDs per character in the string to be translated. The keymap argument can be set to NULL if the default keymap is to be used, or can be a pointer to a '''KeyMap''' structure. Upon return, the function will indicate how many key code/qualifier combinations are placed in the buffer or a negative number in case an error occurred. If zero is returned, the character could not be translated.

The following example shows the usage of '''MapANSI()''' and demonstrates how returned key codes can be processed.

<syntaxhighlight>
/*
mapansi.c - converts a string to input events using MapANSI() function.

This example will also take the created input events
and add them to the input stream using the simple
commodities.library function AddIEvents(). Alternately,
you could open the input.device and use the input device
command IND_WRITEEVENT to add events to the input stream.
*/

#include <exec/types.h>
#include <exec/memory.h>
#include <exec/io.h>
#include <dos/dos.h>
#include <devices/input.h>
#include <devices/inputevent.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/keymap.h>
#include <proto/commodities.h>

struct Library *KeymapBase = NULL; /* MapAnsi() function */
struct KeymapIFace *IKeymap = NULL;

struct Library *CxBase = NULL; /* AddIEvents() function */
struct CommoditiesIFace *ICommodities = NULL;

struct InputEvent *InputEvent = NULL; /* we'll allocate this */

/* prototypes for our program functions */

void openall(void);
void closeall(void);
void closeout(UBYTE *errstring, LONG rc);

int main(int argc, char **argv)
{
UBYTE *string;
UBYTE *tmp1;
UBYTE *tmp2;
UBYTE iebuffer[6]; /* Space for two dead keys */
/* + 1 key + qualifiers */
COUNT i;
LONG rc = 0;

openall();

string = ";String converted to input events and sent to input device\n";

InputEvent->ie_Class = IECLASS_RAWKEY;

/* Turn each character into an InputEvent */
tmp1 = string;

while (*tmp1)
{
/* Convert one character, use default key map */
i = IKeymap->MapANSI(tmp1, 1, iebuffer, 3, NULL);

/* Make sure we start without deadkeys */
InputEvent->ie_Prev1DownCode = InputEvent->ie_Prev1DownQual = 0;
InputEvent->ie_Prev2DownCode = InputEvent->ie_Prev2DownQual = 0;

tmp2 = iebuffer;

switch (i)
{
case -2:
IDOS->Printf("Internal error\n", NULL);
rc = RETURN_FAIL;
break;

case -1:
IDOS->Printf("Overflow\n", NULL);
rc = RETURN_FAIL;
break;

case 0:
IDOS->Printf("Can't generate code\n", NULL);
break;

case 3:
InputEvent->ie_Prev2DownCode = *tmp2++;
InputEvent->ie_Prev2DownQual = *tmp2++;
/* FALL THROUGH */

case 2:
InputEvent->ie_Prev1DownCode = *tmp2++;
InputEvent->ie_Prev1DownQual = *tmp2++;
/* FALL THROUGH */

case 1:
InputEvent->ie_Code = *tmp2++;
InputEvent->ie_Qualifier = *tmp2;
break;
}

if (rc == RETURN_OK)
{
/* Send the key down event */
ICommodities->AddIEvents(InputEvent);

/* Create a key up event */
InputEvent->ie_Code |= IECODE_UP_PREFIX;

/* Send the key up event */
ICommodities->AddIEvents(InputEvent);
}

if (rc != RETURN_OK)
break;

tmp1++;
}

closeall();
return rc;
}

void openall(void)
{
KeymapBase = IExec->OpenLibrary("keymap.library", 50);
IKeymap = (struct KeymapIFace*)IExec->GetInterface(KeymapBase, "main", 1, NULL);
if (IKeymap == NULL) closeout("Can't get IKeymap", RETURN_FAIL);

CxBase = IExec->OpenLibrary("commodities.library", 50);
ICommodities = (struct CommoditiesIFace*)IExec->GetInterface(CxBase, "main", 1, NULL);
if (ICommodities == NULL) closeout("Can't get ICommodities", RETURN_FAIL);

InputEvent = IExec->AllocMem(sizeof(struct InputEvent), MEMF_CLEAR);
if (InputEvent == NULL) closeout("Can't allocate input event",RETURN_FAIL);
}

void closeall()
{
if (InputEvent) IExec->FreeMem(InputEvent, sizeof(struct InputEvent));

IExec->DropInterface((struct Interface*)ICommodities);
IExec->CloseLibrary(CxBase);

IExec->DropInterface((struct Interface*)IKeymap);
IExec->CloseLibrary(KeymapBase);
}

void closeout(UBYTE *errstring, LONG rc)
{
if(*errstring) IDOS->Printf("%s\n",errstring);
closeall();
exit(rc);
}
</syntaxhighlight>

=== Details of the Keymap Structure ===

A '''KeyMap''' structure contains pointers to arrays which determine the translation from raw key codes to ANSI characters.

<syntaxhighlight>
struct KeyMap
{
UBYTE *km_LoKeyMapTypes;
ULONG *km_LoKeyMap;
UBYTE *km_LoCapsable;
UBYTE *km_LoRepeatable;
UBYTE *km_HiKeyMapTypes;
ULONG *km_HiKeyMap;
UBYTE *km_HiCapsable;
UBYTE *km_HiRepeatable;
};
</syntaxhighlight>

==== LoKeyMap and HighKeyMap ====

The low key map provides translation of the key values from hex 00-3F; the high key map provides translation of key values from hex 40-7F. Key values from hex 68-7F are not used by the existing keyboards, but this may change in the future. A raw key value (hex 00-7F) plus hex 80 is the release of that key. If you need to check for raw key releases do it like this:

<syntaxhighlight>
if (keyvalue & 0x80) { /* do key up processing */ }
else { /* do key down processing */ }
</syntaxhighlight>

Raw output from the keyboard for the low key map does not include the space bar, Tab, Alt, Ctrl, arrow keys, and several other keys.

{| class="wikitable"
|+High Key Map Hex Values
|-
!Key Number
!Keycap Legend for Function
|-
|40
|Space
|-
|41
|Backspace
|-
|42
|Tab
|-
|43
|Enter
|-
|44
|Return
|-
|45
|Escape
|-
|46
|Delete
|-
|4A
|Numeric Pad character
|-
|4C
|Cursor Up
|-
|4D
|Cursor Down
|-
|4E
|Cursor Right
|-
|4F
|Cursor Left
|-
|50-59
|Function keys F1-F10
|-
|5A-5E
|Numeric Pad characters
|-
|5F
|Help
|-
|60
|Left Shift
|-
|61
|Right Shift
|-
|62
|Caps Lock
|-
|63
|Control
|-
|64
|Left Alt
|-
|65
|Right Alt
|-
|66
|Left Amiga
|-
|67
|Right Amiga
|}

The keymap table for the low and high keymaps consists of 4-byte entries, one per hex key code. These entries are interpreted in one of two possible ways:

* As four separate bytes, specifying how the key is to be interpreted when pressed alone, with one qualifier, with another qualifier, or with both qualifiers (where a qualifier is one of three possible keys: Ctrl, Alt, or Shift).

* As a longword containing the address of a string descriptor, where a string of characters is to be output when this key is pressed. If a string is to be output, any combination of qualifiers can affect the string that may be transmitted.

* As a longword containing the address of a dead-key descriptor, where additional data describe the character to be output when this key is pressed alone or with another dead key.

{{Note|title=The keymap tables must be word aligned|text=The keymap tables ''must'' begin aligned on a word boundary. Each entry is four bytes long, thereby maintaining word alignment throughout the table. This is necessary because some of the entries may be longword addresses and ''must'' be aligned properly for the 68000.}}

==== LoKeyMapTypes and HiKeyMapTypes ====

The tables named '''km_LoKeyMapTypes''' and '''km_HiKeyMapTypes''' each contain one byte per raw key code. Each byte defines the type of entry that is found in the keymap table for that raw key code.

Possible key types are:

* Any of the qualifier groupings noted above

* KCF_STRING + any combination of KCF_SHIFT, KCF_ALT, KCF_CONTROL (or KC_NOQUAL) if the result of pressing the key is to be a stream of bytes (and key-with-one-or-more-qualifiers is to be one or more alternate streams of bytes). Any key can be made to output up to eight unique byte streams if KCF_STRING is set in its keytype. The only limitation is that the total length of all of the strings assigned to a key must be within the "jump range" of a single byte increment. See the "String Output Keys" section below for more information.

* KCF_DEAD + any combination of KCF_SHIFT, KCF_ALT, KCF_CONTROL (or KC_NOQUAL) if the key is a dead-class key and can thus modify or be modified by another dead-class key. See the "Dead-Class Keys" section below for more information.

The low keytype table covers the raw key codes from hex 00-3F and contains one byte per key code. Therefore this table contains 64 (decimal) bytes. The high keytype table covers the raw key codes from hex 40-7F and contains 64 (decimal) bytes.

==== More About Qualifiers ====

For keys such as the Return key or Esc key, the qualifiers specified in the keytypes table (up to two) are the qualifiers used to establish the response to the key. This is done as follows. In the keytypes table, the values listed for the key types are those listed for the qualifiers in <devices/keymap.h> and <devices/keymap>. Specifically, these qualifier equates are:

{| class="wikitable"
| KC_NOQUAL || 0x00
|-
| KCF_SHIFT || 0x01
|-
| KCF_ALT || 0x02
|-
| KCF_CONTROL || 0x04
|-
| KC_VANILLA || 0x07
|-
| KCF_DOWNUP || 0x08
|-
| KCF_STRING || 0x40
|}

As shown above, the qualifiers for the various types of keys occupy specific bit positions in the key types control byte. As you may have noticed, there are three possible qualifiers, but only a 4-byte space in the table for each key. This does not allow space to describe what the computer should output for all possible combinations of qualifiers. A solution exists, however, for "vanilla" keys, such as the alphabetic keys. Here is how that works.

Keys of type KC_VANILLA use the 4 bytes to represent the data output for the key alone, Shifted key, Alt'ed key, and Shifted-and-Alt'ed key. Then for the Ctrl-key-plus-vanilla-key, use the code for the key alone with bits 6 and 5 set to 0.

{{Note|title=The Vanilla Qualifier Does Not Mean Plain|text=The qualifier KC_VANILLA is equivalent to KCF_SHIFT+KCF_ALT+KCF_CONTROL.
}}

This table shows how to interpret the keymap for various combinations of the qualifier bits:

{| class="wikitable"
|+Keymap Qualifier Bits
|-
| If Keytype is:
| colspan="4" | Then data at this position in the keytable is output when the key is pressed along with:
|-
| KC_NOQUAL || - || - || - || alone
|-
| KCF_SHIFT || - || - || Shift || alone
|-
| KCF_ALT || - || - || Alt || alone
|-
| KCF_CONTROL || - || - || Ctrl || alone
|-
| KCF_ALT+KCF_SHIFT || Shift+Alt || Alt || Shift || alone
|-
| KCF_CONTROL+KCF_ALT || Ctrl+Alt || Ctrl || Alt || alone
|-
| KCF_CONTROL+KCF_SHIFT || Ctrl+Shift || Ctrl || Shift || alone
|-
| KC_VANILLA || Shift+Alt || Alt || Shift || alone*
|-
| colspan = "5" | *Special case--Ctrl key, when pressed with one of the alphabet keys and certain others, is to output key-alone value with the bits 6 and 5 set to zero.
|}

==== String Output Keys ====

When a key is to output a string, the keymap table contains the address of a string descriptor in place of a 4-byte mapping of a key as shown above. Here is a partial table for a new high keymap table that contains only three entries thus far. The first two are for the space bar and the backspace key; the third is for the tab key, which is to output a string that says "[TAB]". An alternate string, "[SHIFTED-TAB]", is also to be output when a shifted TAB key is pressed.

<pre>
newHiMapTypes:
DC.B KCF_ALT,KC_NOQUAL, ;key 41
DC.B KCF_STRING+KCF_SHIFT, ;key 42
... ;(more)
newHiMap:
DC.B 0,0,$A0,$20 ;key 40: space bar, and Alt-space bar
DC.B 0,0,0,$08 ;key 41: Back Space key only
DC.L newkey42 ;key 42: new definition for string to output for Tab key
... ;(more)
newkey42:
DC.B new42ue - new42us ;length of the unshifted string
DC.B new42us - newkey42 ;number of bytes from start of
;string descriptor to start of this string
DC.B new42se - new42ss ;length of the shifted string
DC.B new42ss - newkey42 ;number of bytes from start of
;string descriptor to start of this string
new42us: DC.B '[TAB]'
new42ue:
new42ss: DC.B '[SHIFTED-TAB]'
new42se:
</pre>

The new high map table points to the string descriptor at address newkey42. The new high map types table says that there is one qualifier, which means that there are two strings in the key string descriptor.

Each string in the descriptor takes two bytes in this part of the table: the first byte is the length of the string, and the second byte is the distance from the start of the descriptor to the start of the string. Therefore, a single string (KCF_STRING + KC_NOQUAL) takes 2 bytes of string descriptor. If there is one qualifier, 4 bytes of descriptor are used. If there are two qualifiers, 8 bytes of descriptor are used. If there are 3 qualifiers, 16 bytes of descriptor are used. All strings start immediately following the string descriptor in that they are accessed as single-byte offsets from the start of the descriptor itself. Therefore, the distance from the start of the descriptor to the last string in the set (the one that uses the entire set of specified qualifiers) must start within 255 bytes of the descriptor address.

Because the length of the string is contained in a single byte, the length of any single string must be 255 bytes or less while also meeting the "reach" requirement. However, the console input buffer size limits the string output from any individual key to 32 bytes maximum.

The length of a keymap containing string descriptors and strings is variable and depends on the number and size of the strings that you provide.

==== Capsable Bit Tables ====

The vectors '''km_LoCapsable''' and '''km_HiCapsable''' each point to an array of 8 bytes that contain more information about the keytable entries. Specifically, if the Caps Lock key has been pressed (the Caps Lock LED is on) and if there is a bit \fIon\fP in that position in the capsable map, then this key will be treated as though the Shift key is now currently pressed. For example, in the default key mapping, the alphabetic keys are "capsable" but the punctuation keys are not. This allows you to set the Caps Lock key, just as on a normal typewriter, and get all capital letters. However, unlike a normal typewriter, you need not go out of Caps Lock to correctly type the punctuation symbols or numeric keys.

In the byte array, the bits that control this feature are numbered from the lowest bit in the byte, and from the lowest memory byte address to the highest. For example, the bit representing capsable status for the key that transmits raw code 00 is bit 0 in byte 0; for the key that transmits raw code 08 it is bit 0 in byte 1, and so on.

There are 64 bits (8 bytes) in each of the two capsable tables.

==== Repeatable Bit Tables ====

The vectors '''km_LoRepeatable''' and '''km_HiRepeatable''' each point to an array of 8 bytes that contain additional information about
the keytable entries. A bit for each key indicates whether or not the specified key should repeat at the rate set by the Input Preferences program.

The bit positions correspond to those specified in the capsable bit table. If there is a 1 in a specific position, the key can repeat. There are 64 bits (8 bytes) in each of the two repeatable tables.

=== Key Map Standards ===

Users and programs depend on certain predictable behaviors from all keyboards and keymaps. With the exception of dead-class keys (see "Dead-Class Keys" section), mapping of keys in the low key map should follow these general rules:

* When pressed alone, keys should transmit the ASCII equivalent of the unshifted letter or lower symbol on the keycap.

* When Shifted, keys should transmit the ASCII equivalent of the shifted letter or upper symbol printed on the keycap.

* When Alt'ed, keys should generally transmit the same character (or act as the same deadkey) as the Alt'ed key in the usa1 keymap.

* When pressed with CTRL alone, alphabetic keys should generally transmit their unshifted value but with bits 5 and 6 cleared. This allows keyboard typing of "control characters." For example, the C key (normally value $63) should transmit value $03 (Ctrl-C) when Ctrl and C are pressed together.

The keys in the high key map (keys with raw key values $40 and higher) are generally non-alphanumeric keys such as those used for editing
(backspace, delete, cursor keys, etc.), and special Amiga keys such as the function and help keys. Keymaps should translate these keys to the same values or strings as those shown in ROM Default Key Mapping table.

In addition to their normal unshifted and shifted values, the following translations are standard for particular qualified high keymap keys:

{| class="wikitable"
! Key
! Generates This Value
! If Used with Qualifier, Generates This Value
|-
| Space || $20 || $A0 with qualifier KCF_ALT
|-
| Return || $0D || $0A with qualifier KCF_CONTROL
|-
| Esc || $1B || $9B with qualifier KCF_ALT
|}

=== Dead-Class Keys ===

All of the national keymaps, including USA, contain ''dead-class'' keys. This term refers to keys that either modify or can themselves be modified by other dead-class keys. There are two types of dead-class keys: dead and deadable. A dead key is one which can modify certain keys pressed immediately following. For example, on the German keyboard there is a dead key marked with the grave accent (`). The dead key produces no console output, but when followed by (for instance) the A key, the combination will produce the a-grave (à) character (National Character Code $E0). On the U.S. keyboard, Alt-G is the deadkey used to add the grave accent (`) to the next appropriate character typed.

A deadable key is one that can be prefixed by a dead key. The A key in the previous example is a deadable key. Thus, a dead key can only affect the output of a deadable key.

For any key that is to have a dead-class function, whether dead or deadable, the qualifier KCF_DEAD flag must be included in the entry for the key in the KeyMapTypes table. The KCF_DEAD type may also be used in conjunction with the other qualifiers. Furthermore, the key's keymap table entry must contain the longword address of the key's dead-key descriptor data area in place of the usual 4 ASCII character mapping.

Below is an excerpt from the Amiga 1000 German key map which is referred to in the following discussion.

<pre>
KMLowMapType:
DC.B KCF_DEAD+KC_VANILLA ; aA (Key 20)
... ; (more...)
DC.B KCF_DEAD+KC_VANILLA ; hH (Key 25)
... ; (more...)
KMLowMap:
DC.L key20 ; a, A, ae, AE
... ; (more...)
DC.L key25 ; h, H, dead ^
... ; (more...)
;------ possible dead keys
key25:
DC.B 0,'h',0,'H' ; h, H
DC.B DPF_DEAD,3,DPF_DEAD,3 ; dead ^, dead ^
DC.B 0,$08,0,$08,0,$88,0,$88 ; control translation
... ; (more...)
;------ deadable keys (modified by dead keys)
key20: ; a, A, ae, AE
DC.B DPF_MOD,key20u-key20 ; deadable flag, number of
; bytes from start of key20
; descriptor to start of un-
; shifted data
DC.B DPF_MOD,key20s-key20 ; deadable flag, number of
; bytes from start of key20
; descriptor to start of shift-
; ed data
DC.B 0,$E6,0,$C6 ; null flags followed by rest
DC.B 0,$01,0,$01,0,$81,0,$81 ; of values (ALT, CTRL...)
key20u:
DC.B 'a',$E1,$E0,$E2,$E3,$E4 ; 'a' alone and characters to
; output when key alone is
; prefixed by a dead key
DC.B $E1,$E1,$E2,$E1,$E1,$E1 ; most recent is '
DC.B $E0,$E2,$E0,$E0,$E0,$E0 ; most recent is `
key20s:
DC.B 'A',$C1,$C0,$C2,$C3,$C4 ; SHIFTed 'a' and characters to
; output when SHIFTed key is
; prefixed by a dead key
DC.B $C1,$C1,$C2,$C1,$C1,$C1 ; most recent is '
DC.B $C0,$C2,$C0,$C0,$C0,$C0 ; most recent is `
</pre>

In the example, key 25 (the H key) is a dead key and key 20 (the A key) is a deadable key. Both keys use the addresses of their descriptor data areas as entries in the LoKeyMap table. The LoKeyMapTypes table says that there are four qualifiers for both: the requisite KCF_DEAD, as well as KCF_SHIFT, KCF_ALT, and KCF_CONTROL. The number of qualifiers determine length and arrangement of the descriptor data areas for each key. The next table shows how to interpret the KeyMapTypes for various combinations of the qualifier bits. For each possible position a pair of bytes is needed. The first byte in each pair tells how to interpret the second byte (more about this below).

{| class="wikitable"
|+Dead Key Qualifier Bits
|-
! If type is:
! colspan="8" | Then the pair of bytes in this position in the dead-class key descriptor data is output when the key is pressed along with:
|-
| NOQUAL || alone || - || - || - || - || - || - || -
|-
| A || alone || - || - || - || - || - || - || -
|-
| C || alone || C || - || - || - || - || - || -
|-
| S || alone || S || - || - || - || - || - || -
|-
| A+C || alone || A || C || A+C || - || - || - || -
|-
| A+S || alone || S || A || A+S || - || - || - || -
|-
| C+S || alone || S || C || C+S || - || - || - || -
|-
| S+A+C (VANILLA) || alone || S || A || S+A || C || C+S || C+A || C+S+A
|-
| colspan="9" | The abbreviations A, C, S stand for KCF_ALT, KCF_CONTROL, and KCF_SHIFT, respectively. Also note that the ordering is reversed from that in the normal '''KeyMap''' table.
|}

Because keys 20 and 25 each use three qualifier bits (not including KCF_DEAD), according to the table there must be 8 pairs of data, arranged as shown. Had only KCF_ALT been set, for instance, (not including KCF_DEAD), just two pairs would have been needed.

As mentioned earlier, the first byte of each data pair in the descriptor data area specifies how to interpret the second byte. There are three possible values: 0, DPF_DEAD and DPF_MOD. In the Amiga 1000 German keymap listed above, DPF_DEAD appears in the data for key 25, while DPF_MOD is used for key 20. It is the use of these flags that determines whether a dead-class key has dead or deadable function. A value of zero causes the unrestricted output of the following byte.

If the flag byte is DPF_DEAD, then that particular key combination (determined by the placement of the pair of bytes in the data table) is dead and will modify the output of the next key pressed (if deadable). How it modifies is controlled by the second byte of the pair which is used as an index into part(s) of the data area for ALL the deadable (DPF_MOD set) keys.

Before going further, an understanding of the structure of a descriptor data area wherein DPF_MOD is set for one (or more) of its members is necessary. Referring to the example, we see that DPF_MOD is set for the first and second pairs of bytes. According to its LoKeyMapTypes entry, and using table above (Dead Key Qualifier Bits) as a guide, these pairs represent the alone and SHIFTed values for the key. When DPF_MOD is set, the byte immediately following the flag must be the offset from the start of the key's descriptor data area to the start of a table of bytes describing the characters to output when this key combination is preceded by any dead keys. This is where the index mentioned above comes in. The value of the index from a prefixing dead key is used to determine which of the bytes from the deadable keys special table to output. The byte in the index+1 position is sent out. (The very first byte is the value to output if the key was not prefixed by a dead key.) Thus, if Alt-H is pressed (dead) and then Shift-A, an 'a' with a circumflex (^) accent will be output. This is because:

* The byte pair for the ALT position of the "H" key (key 25) is DPF_DEAD,3 so the index is 3.

* The byte pair for the SHIFT position of the "A" key (key 20) is DPF_MOD, key20s-key20, so we refer to the table-of-bytes at key20s.

* The third+1 byte of the table-of-bytes is $C2, an 'a' character.

{{Note|title=A Note About Table Size|text=The number of bytes in the table-of-bytes for all deadable keys must be equal to the highest index value of all dead keys plus 1.}}

=== Double-Dead Keys ===

Double-dead keys are an extension of the dead-class keys explained above. Unlike normal dead keys wherein one dead key of type DPF_DEAD can modify a second of type DPF_MOD, double-dead keys employ two consecutive keys of type DPF_DEAD to together modify a third of type DPF_MOD.

For example, the key on the German keyboard labeled with single quotes (<nowiki>''</nowiki>) is a double-dead key. When this key is pressed alone and then pressed again shifted, there is no output. But when followed by an appropriate third key, for example the A key, the three keypresses combine to produce an 'a' with a circumflex (^) accent (character code $E2). Thus the double-dead pair qualify the output of the A key.

The system always keeps the last two down key codes for possible further translation. If they are both of type DPF_DEAD and the key immediately following is DPF_MOD then the two are used to form an index into the (third) key's translation table as follows:

In addition to the index found after the DPF_DEAD qualifier in a normal dead key, a second factor is included in the high nibble of double-dead keys (it is shifted into place with DP_2DFACSHIFT). Its value equals the total number of dead key types + 1 in the keymap. This second index also serves as an identifying flag to the system that two dead keys can be significant.

When a key of type DPF_MOD is pressed, the system checks the two key codes which preceded the current one. If they were both DPF_DEAD then the most recent of the two is checked for the double-dead index/flag. If it is found then a new index is formed by multiplying the value in lower nibble with that in the upper. Then, the lower nibble of the least recent DPF_DEAD key is added in to form the final offset.

Finally, this last value is used as an index into the translation table of the current, DPF_MOD, key.

The translation table of all deadable (DPF_MOD) keys has [number of dead key types + 1] * [number of double dead key types + 1] entries, arranged in [number of double dead key types + 1] rows of [number of dead key types + 1] entries. This is because as indices are assigned for dead keys in the keymap, those that are double dead keys are assigned the lower numbers.

Following is a code fragment from the German (d) keymap source:

<pre>
key0C:
DC.B DPF_DEAD,1+(6<<DP_2DFACSHIFT) ; dead '
DC.B DPF_DEAD,2+(6<<DP_2DFACSHIFT) ; dead `
DC.B 0,'=',0,'+' ; =, +
key20: ; a, A, ae, AE
DC.B DPF_MOD,key20u-key20,DPF_MOD,key20s-key20
DC.B 0,$E6,0,$C6
DC.B 0,$01,0,$01,0,$81,0,$81 ; control translation
key20u:
DC.B 'a',$E1,$E0,$E2,$E3,$E4
DC.B $E1,$E1,$E2,$E1,$E1,$E1 ; most recent is '
DC.B $E0,$E2,$E0,$E0,$E0,$E0 ; most recent is `
key20s:
DC.B 'A',$C1,$C0,$C2,$C3,$C4
DC.B $C1,$C1,$C2,$C1,$C1,$C1 ; most recent is '
DC.B $C0,$C2,$C0,$C0,$C0,$C0 ; most recent is `
</pre>

Raw key0C, the German single quotes (<nowiki>''</nowiki>) key, is a double dead key. Pressing this key alone, then again while the shift key is down will produce no output but will form a double-dead qualifier. The output of key20 (A), a deadable key, will consequently be modified, producing an "a" with a circumflex (^) accent. The mechanics are as follows:

* When key0C is pressed alone the DPF_DEAD of the first byte pair in the key's table indicates that the key as dead. The second byte is then held by the system.

* Next, when key0C is pressed again, this time with the Shift key down, the DPF_DEAD of the second byte pair (recall that the second pair is used because of the SHIFT qualifier) again indicates the key is a dead key. The second byte of this pair is also held by the system.

* Finally, when the A key is pressed the system recalls the latter of the two bytes it has saved. The upper nibble, $6, is multiplied by
the lower nibble, $2. The result, $0C, is then added to the lower nibble of the earlier of the two saved bytes, $1. This new value, $0D, is used as an index into the (unshifted) translation table of key20. The character at position $0D is character $E2, an 'a' with a circumflex (^) accent.

{{Note|title=Note About Double Dead Keys|text=If only one double-dead key is pressed before a deadable key then the output is the same as if the double-dead were a normal dead key. If shifted key0C is pressed on the German keyboard and then immediately followed by key20, the output produced is character $E0 'à'. As before, the upper nibble is multiplied with the lower, resulting in $0C. But because there was no second dead-key, this product is used as the final index.}}

== Keyboard Layout ==

The keys with key codes $2B and $30 in the following keyboard diagrams are keys which are present on some national Amiga keyboards.

[[File:LibFig34-1.png|800px|Amiga 1000 Keyboard Showing Key Codes in Hex]]

[[File:LibFig34-2.png|800px|Amiga 500/2000 Keyboard Showing Key Codes in Hex]]

The default values given above correspond to the values the console device will return when these keys are pressed with the keycaps as shipped with the standard American keyboard.

{| class="wikitable"
|+ROM Default (USA0) and USA1 Console Key Mapping
|-
! Raw Key Number
! Keycap Legend
! Unshifted Default Value
! Shifted Default Value
|-
| 00 || `~ || ` (Accent grave) || ~ (tilde)
|-
| 01 || 1 ! || 1 || !
|-
| 02 || 2 @ || 2 || @
|-
| 03 || 3 # || 3 || #
|-
| 04 || 4 $ || 4 || $
|-
| 05 || 5 % || 5 || %
|-
| 06 || 6 ^ || 6 || ^
|-
| 07 || 7 & || 7 || &
|-
| 08 || 8 * || 8 ||
|-
| 09 || 9 ( || 9 || (
|-
| 0A || 0 ) || 0 || )
|-
| 0B || - _ || - (Hyphen) || _ (Underscore)
|-
| 0C || = + || = || +
|-
| 0D || | | || || | |
|-
| 0E || (undefined) ||
|-
| 0F || 0 || 0 || 0 (Numeric pad)
|-
| 10 || Q || q || Q
|-
| 11 || W || w || W
|-
| 12 || E || e || E
|-
| 13 || R || r || R
|-
| 14 || T || t || T
|-
| 15 || Y || y || Y
|-
| 16 || U || u || U
|-
| 17 || I || i || I
|-
| 18 || O || o || O
|-
| 19 || P || p || P
|-
| 1A || [ { || [ || {
|-
| 1B || ] } || ] || }
|-
| 1C || || (undefined) ||
|-
| 1D || 1 || 1 || 1 (Numeric pad)
|-
| 1E || 2 || 2 || 2 (Numeric pad)
|-
| 1F || 3 || 3 || 3 (Numeric pad)
|-
| 20 || A || a || A
|-
| 21 || S || s || S
|-
| 22 || D || d || D
|-
| 23 || F || f || F
|-
| 24 || G || g || G
|-
| 25 || H || h || H
|-
| 26 || J || j || J
|-
| 27 || K || k || K
|-
| 28 || L || l || L
|-
| 29 || ; : || ; || :
|-
| 2A || ' " || ' (single quote) || "
|-
| 2B || || (not on most U.S. keyboards) ||
|-
| 2C || || (undefined) ||
|-
| 2D || 4 || 4 || 4 (Numeric pad)
|-
| 2E || 5 || 5 || 5 (Numeric pad)
|-
| 2F || 6 || 6 || 6 (Numeric pad)
|-
| 30 || || (not on most U.S. keyboards) ||
|-
| 31 || Z || z || Z
|-
| 32 || X || x || X
|-
| 33 || C || c || C
|-
| 34 || V || v || V
|-
| 35 || B || b || B
|-
| 36 || N || n || N
|-
| 37 || M || m || M
|-
| 38 || , < || , (comma) || <
|-
| 39 || . > || . (period) || >
|-
| 3A || / ? || / || ?
|-
| 3B || || (undefined) ||
|-
| 3C || . || . || . (Numeric pad)
|-
| 3D || 7 || 7 || 7 (Numeric pad)
|-
| 3E || 8 || 8 || 8 (Numeric pad)
|-
| 3F || 9 || 9 || 9 (Numeric pad)
|-
| 40 || Space bar || 0x20 || 0x20
|-
| 41 || Back Space || 0x08 || 0x08
|-
| 42 || Tab || 0x09 || 0x09
|-
| 43 || Enter || 0x0D || 0x0D
|-
| 44 || Return || 0x0D || 0x0D (Numeric pad)
|-
| 45 || Esc || 0x1B || 0x1B
|-
| 46 || Del || 0x7F || 0x7F
|-
| 47 || || (undefined) ||
|-
| 48 || || (undefined) ||
|-
| 49 || || (undefined) ||
|-
| 4A || - || - || - (Numeric Pad)
|-
| 4B || || (undefined) ||
|-
| 4C || Up arrow || <CSI>A || <CSI>T
|-
| 4D || Down arrow || <CSI>B || <CSI>S
|-
| 4E || Forward arrow || <CSI>C || <CSI> A (note blank space after <CSI>)
|-
| 4F || Backward arrow || <CSI>D || <CSI> @ (note blank space after <CSI>)
|-
| 50 || F1 || <CSI>0~ || <CSI>10~
|-
| 51 || F2 || <CSI>1~ || <CSI>11~
|-
| 52 || F3 || <CSI>2~ || <CSI>12~
|-
| 53 || F4 || <CSI>3~ || <CSI>13~
|-
| 54 || F5 || <CSI>4~ || <CSI>14~
|-
| 55 || F6 || <CSI>5~ || <CSI>15~
|-
| 56 || F7 || <CSI>6~ || <CSI>16~
|-
| 57 || F8 || <CSI>7~ || <CSI>17~
|-
| 58 || F9 || <CSI>8~ || <CSI>18~
|-
| 59 || F10 || <CSI>9~ || <CSI>19~
|-
| 5A || ( || ( || ( (usa1 Numeric pad)
|-
| 5B || ) || ) || ) (usa1 Numeric pad)
|-
| 5C || / || / || / (usa1 Numeric pad)
|-
| 5D || * || * || * (usa1 Numeric pad)
|-
| 5E || + || + || + (usa1 Numeric pad)
|-
| 5F || Help || <CSI>?~ || <CSI>?~
|}

{| class="wikitable"
! Raw Key Number
! Function or Keycap Legend
|-
| 60 || Shift (left of space bar)
|-
| 61 || Shift (right of space bar)
|-
| 62 || Caps Lock
|-
| 63 || Ctrl
|-
| 64 || (Left) Alt
|-
| 65 || (Right) Alt
|-
| 66 || Amiga (left of space bar)
|-
| 67 || Amiga (right of space bar)
|-
| 68 || Left mouse button (not converted)
|-
| 69 || Right mouse button (not converted)
|-
| 6A || Middle mouse button (not converted)
|-
| 6B || (undefined)
|-
| 6C || (undefined)
|-
| 6D || (undefined)
|-
| 6E || (undefined)
|-
| 6F || (undefined)
|-
| 70-7F || (undefined)
|-
| 80-F8 || Up transition (release or unpress key of one of the above keys) (80 for 00, F8 for 7F)
|-
| F9 || Last key code was bad (was sent in order to resynchronize)
|-
| FA || Keyboard buffer overflow
|-
| FB || (undefined, reserved for keyboard processor catastrophe)
|-
| FC || Keyboard selftest failed
|-
| FD || Power-up key stream start. Keys pressed or stuck at power-up will be sent between FD and FE.
|-
| FE || Power-up key stream end
|-
| FF || (undefined, reserved)
|-
| FF || Mouse event, movement only, no button change (not converted)
|}

Notes about the preceding table:

# "<CSI>" is the Control Sequence Introducer, value hex 9B.
# (undefined)" indicates that the current keyboard design should not generate this number. If you are using '''SetKeyMap()''' to change the key map, the entries for these numbers must still be included.
# "(not converted)" refers to mouse button events. You must use the sequence "<CSI>2{" to inform the console driver that you wish to receive mouse events; otherwise these will not be transmitted.
# "(RESERVED)" indicates that these key codes have been reserved for national keyboards. The $2B code key will be between the double-quote (") and Return keys. The $30 code key will be between the Shift and Z keys.

[[File:LibFig34-3.png|frame|center|ECMA-94 Latin 1 International 8-Bit Character Set]]

== Raw Key Table ==

The following table defines all of the Amiga raw key codes and what they mean.

{{Note|All values are in hexadecimal}}

{| class="wikitable"
! Raw Key
! USB Page
! USB Code
! PS2 Set 1 Code
! PS2 Set 2 Code
! Name
! Classic Amiga Key
|-
| 0000 || 0007 || 0035 || 0029 || 000E || || <nowiki>`~</nowiki>
|-
| 0001 || 0007 || 001E || 0002 || 0016 || || <nowiki>1!</nowiki>
|-
| 0002 || 0007 || 001F || 0003 || 001E || || <nowiki>2@</nowiki>
|-
| 0003 || 0007 || 0020 || 0004 || 0026 || || <nowiki>3#</nowiki>
|-
| 0004 || 0007 || 0021 || 0005 || 0025 || || <nowiki>4$</nowiki>
|-
| 0005 || 0007 || 0022 || 0006 || 002E || || <nowiki>5%</nowiki>
|-
| 0006 || 0007 || 0023 || 0007 || 0036 || || <nowiki>6^</nowiki>
|-
| 0007 || 0007 || 0024 || 0008 || 003D || || <nowiki>7&</nowiki>
|-
| 0008 || 0007 || 0025 || 0009 || 003E || || <nowiki>8*</nowiki>
|-
| 0009 || 0007 || 0026 || 000A || 0046 || || <nowiki>9(</nowiki>
|-
| 000A || 0007 || 0027 || 000B || 0045 || || <nowiki>0)</nowiki>
|-
| 000B || 0007 || 002D || 000C || 004E || || <nowiki>-_</nowiki>
|-
| 000C || 0007 || 002E || 000D || 0055 || || <nowiki>=+</nowiki>
|-
| 000D || 0007 || 0031 || || || || <nowiki>\|</nowiki> near Backspace
|-
| 000E || 0007 || 0089 || 007D || 006A || || Intl 3 Yen
|-
| 000F || 0007 || 0062 || 0052 || 0070 || || NP <nowiki>0</nowiki>
|-
| 0010 || 0007 || 0014 || 0010 || 0015 || || <nowiki>qQ</nowiki>
|-
| 0011 || 0007 || 001A || 0011 || 001D || || <nowiki>wW</nowiki>
|-
| 0012 || 0007 || 0008 || 0012 || 0024 || || <nowiki>eE</nowiki>
|-
| 0013 || 0007 || 0015 || 0013 || 002D || || <nowiki>rR</nowiki>
|-
| 0014 || 0007 || 0017 || 0014 || 002C || || <nowiki>tT</nowiki>
|-
| 0015 || 0007 || 001C || 0015 || 0035 || || <nowiki>yY</nowiki>
|-
| 0016 || 0007 || 0018 || 0016 || 003C || || <nowiki>uU</nowiki>
|-
| 0017 || 0007 || 000C || 0017 || 0043 || || <nowiki>iI</nowiki>
|-
| 0018 || 0007 || 0012 || 0018 || 0044 || || <nowiki>oO</nowiki>
|-
| 0019 || 0007 || 0013 || 0019 || 004D || || <nowiki>pP</nowiki>
|-
| 001A || 0007 || 002F || 001A || 0054 || || <nowiki>[{</nowiki>
|-
| 001B || 0007 || 0030 || 001B || 005B || || <nowiki>]}</nowiki>
|-
| 001C || || || || || || undefined
|-
| 001D || 0007 || 0059 || 004F || 0069 || || NP <nowiki>1</nowiki>
|-
| 001E || 0007 || 005A || 0050 || 0072 || || NP <nowiki>2</nowiki>
|-
| 001F || 0007 || 005B || 0051 || 007A || || NP <nowiki>3</nowiki>
|-
| 0020 || 0007 || 0004 || 001E || 001C || || <nowiki>aA</nowiki>
|-
| 0021 || 0007 || 0016 || 001F || 001B || || <nowiki>sS</nowiki>
|-
| 0022 || 0007 || 0007 || 0020 || 0023 || || <nowiki>dD</nowiki>
|-
| 0023 || 0007 || 0009 || 0021 || 002B || || <nowiki>fF</nowiki>
|-
| 0024 || 0007 || 000A || 0022 || 0034 || || <nowiki>gG</nowiki>
|-
| 0025 || 0007 || 000B || 0023 || 0033 || || <nowiki>hH</nowiki>
|-
| 0026 || 0007 || 000D || 0024 || 003B || || <nowiki>jJ</nowiki>
|-
| 0027 || 0007 || 000E || 0025 || 0042 || || <nowiki>kK</nowiki>
|-
| 0028 || 0007 || 000F || 0026 || 004B || || <nowiki>lL</nowiki>
|-
| 0029 || 0007 || 0033 || 0027 || 004C || || <nowiki>;:</nowiki>
|-
| 002A || 0007 || 0034 || 0028 || 0052 || || <nowiki>'"</nowiki>
|-
| 002B || 0007 || 0032 || 002B || 005D || || Intl 1 near Return
|-
| 002C || || || || || || undefined
|-
| 002D || 0007 || 005C || 004B || 006B || || NP <nowiki>4</nowiki>
|-
| 002E || 0007 || 005D || 004C || 0073 || || NP <nowiki>5</nowiki>
|-
| 002F || 0007 || 005E || 004D || 0074 || || NP <nowiki>6</nowiki>
|-
| 0030 || 0007 || 0064 || 0056 || 0061 || || Intl 2 near LShift
|-
| 0031 || 0007 || 001D || 002C || 001A || || <nowiki>zZ</nowiki>
|-
| 0032 || 0007 || 001B || 002D || 0022 || || <nowiki>xX</nowiki>
|-
| 0033 || 0007 || 0006 || 002E || 0021 || || <nowiki>cC</nowiki>
|-
| 0034 || 0007 || 0019 || 002F || 002A || || <nowiki>vV</nowiki>
|-
| 0035 || 0007 || 0005 || 0030 || 0032 || || <nowiki>bB</nowiki>
|-
| 0036 || 0007 || 0011 || 0031 || 0031 || || <nowiki>nN</nowiki>
|-
| 0037 || 0007 || 0010 || 0032 || 003A || || <nowiki>mM</nowiki>
|-
| 0038 || 0007 || 0036 || 0033 || 0041 || || <nowiki>,<</nowiki>
|-
| 0039 || 0007 || 0037 || 0034 || 0049 || || <nowiki>.></nowiki>
|-
| 003A || 0007 || 0038 || 0035 || 004A || || <nowiki>/?</nowiki>
|-
| 003B || 0007 || 0087 || 0073 || 0051 || || <nowiki>/?</nowiki> Brazil (near RShift) and International 1 (Ro)
|-
| 003C || 0007 || 0063 || 0053 || 0071 || || NP <nowiki>.</nowiki>
|-
| 003D || 0007 || 005F || 0047 || 006C || || NP <nowiki>7</nowiki>
|-
| 003E || 0007 || 0060 || 0048 || 0075 || || NP <nowiki>8</nowiki>
|-
| 003F || 0007 || 0061 || 0049 || 007D || || NP <nowiki>9</nowiki>
|-
| 0040 || 0007 || 002C || 0039 || 0029 || SPACE || Space
|-
| 0041 || 0007 || 002A || 000E || 0066 || BACKSPACE || Backspace
|-
| 0042 || 0007 || 002B || 000F || 000D || TAB || Tab
|-
| 0043 || 0007 || 0058 || 00E01C || 00E05A || ENTER || NP Enter
|-
| 0044 || 0007 || 0028 || 001C || 005A || RETURN || Return
|-
| 0045 || 0007 || 0029 || 0001 || 0076 || ESC || Escape
|-
| 0046 || 0007 || 004C || 00E053 || 00E071 || DEL || Delete
|-
| 0047 || 0007 || 0049 || 00E052 || 00E070 || INSERT || Insert
|-
| 0048 || 0007 || 004B || 00E049 || 00E07D || PAGE_UP || PageUp
|-
| 0049 || 0007 || 004E || 00E051 || 00E07A || PAGE_DOWN || PageDown
|-
| 004A || 0007 || 0056 || 004A || 007B || || NP <nowiki>-</nowiki>
|-
| 004B || 0007 || 0044 || 0057 || 0078 || F11 || F11
|-
| 004C || 0007 || 0052 || 00E048 || 00E075 || CURSOR_UP || CrsrUp
|-
| 004D || 0007 || 0051 || 00E050 || 00E072 || CURSOR_DOWN || CrsrDown
|-
| 004E || 0007 || 004F || 00E04D || 00E074 || CURSOR_RIGHT || CrsrRight
|-
| 004F || 0007 || 0050 || 00E04B || 00E06B || CURSOR_LEFT || CrsrLeft
|-
| 0050 || 0007 || 003A || 003B || 0005 || F1 || F1
|-
| 0051 || 0007 || 003B || 003C || 0006 || F2 || F2
|-
| 0052 || 0007 || 003C || 003D || 0004 || F3 || F3
|-
| 0053 || 0007 || 003D || 003E || 000C || F4 || F4
|-
| 0054 || 0007 || 003E || 003F || 0003 || F5 || F5
|-
| 0055 || 0007 || 003F || 0040 || 000B || F6 || F6
|-
| 0056 || 0007 || 0040 || 0041 || 0083 || F7 || F7
|-
| 0057 || 0007 || 0041 || 0042 || 000A || F8 || F8
|-
| 0058 || 0007 || 0042 || 0043 || 0001 || F9 || F9
|-
| 0059 || 0007 || 0043 || 0044 || 0009 || F10 || F10
|-
| 005A || || || || || || NP <nowiki>(</nowiki>
|-
| 005B || || || || || || NP <nowiki>)</nowiki>
|-
| 005C || 0007 || 0054 || 00E035 || 00E04A || || NP <nowiki>/</nowiki>
|-
| 005D || 0007 || 0055 || 0037 || 007C || || NP <nowiki>*</nowiki>
|-
| 005E || 0007 || 0057 || 004E || 0079 || || NP <nowiki>+</nowiki>
|-
| 005F || 0007 || 0075 || 0046 || 007E || HELP || Help (maps to ScrollLock on PS/2)
|-
| 0060 || 0007 || 00E1 || 002A || 0012 || LSHIFT || LShift
|-
| 0061 || 0007 || 00E5 || 0036 || 0059 || RSHIFT || RShift
|-
| 0062 || 0007 || 0039 || 003A || 0058 || CAPSLOCK || CapsLock
|-
| 0063 || 0007 || 00E0 || 001D || 0014 || CONTROL || LControl
|-
| 0064 || 0007 || 00E2 || 0038 || 0011 || LALT || LAlt
|-
| 0065 || 0007 || 00E6 || 00E038 || 00E011 || RALT || RAlt
|-
| 0066 || 0007 || 00E3 || 00E05B || 00E01F || LCOMMAND || LAmiga, LWin, LApple, LMeta
|-
| 0067 || 0007 || 00E7 || 00E05C || 00E027 || RCOMMAND || RAmiga, RWin, RApple, RMeta
|-
| 0068 || || || || || LBUTTON || LMouse reserved
|-
| 0069 || || || || || RBUTTON || RMouse reserved
|-
| 006A || || || || || MBUTTON || MMouse reserved
|-
| 006B || 0007 || 0065 || 00E05D || 00E02F || MENU || Menu, Windows, Compose (mappable to RAmiga in Firmware)
|-
| 006C || 0007 || 0085 || 007E || 006D || || Brazil NP <nowiki>.</nowiki> (named "Keypad <nowiki>,</nowiki>" in USB specs)
|-
| 006D || 0007 || 0046 || 00E037 || 00E07C || PRINTSCREEN || PrintScreen/SysReq (mappable to Help in Firmware)
|-
| 006E || 0007 || 0048 || 00E046 || 00E07E || BREAK || Break, Ctrl-Pause on PS/2
|-
| 006F || 0007 || 0045 || 0058 || 0007 || F12 || F12
|-
| 0070 || 0007 || 004A || 00E047 || 00E06C || HOME || Home
|-
| 0071 || 0007 || 004D || 00E04F || 00E069 || END || End
|-
| 0072 || 000C || 00B7 || 00E024 || 00E03B || AUD_STOP || Stop, CD32 Blue Stop, CDTV Stop, Port 0 Blue
|-
| 0073 || 000C || 00CD || 00E022 || E034 || AUD_PLAY_PAUSE || Play/Pause, CD32 Grey Play/Pause, CDTV Play/Pause, Port 0 Play
|-
| 0074 || 000C || 00B6 || 00E010 || E015 || AUD_PREV_TRACK || Prev Track, CD32 Charcoal Reverse, CDTV <nowiki><<</nowiki> REW, Port 0 Reverse
|-
| 0075 || 000C || 00B5 || 00E019 || E04D || AUD_NEXT_TRACK || Next Track, CD32 Charcoal Forward, CDTV <nowiki>>></nowiki> FF, Port 0 Forward
|-
| 0076 || 000C || 00B9 || || || AUD_SHUFFLE || Random Play, CD32 Green Shuffle, Port 0 Green
|-
| 0077 || 000C || 00BC || || || AUD_REPEAT || Repeat, CD32 Yellow Repeat, Port 0 Yellow
|-
| 0078 || || || || || || Port 0 Red
|-
| 0079 || || || || || || Port 0 Joystick Up
|-
| 007A || || || || || || Port 0 Joystick Down
|-
| 007B || || || || || || Port 0 Joystick Right
|-
| 007C || || || || || || Port 0 Joystick Left
|-
| 007D || || || || || || undefined
|-
| 007E || || || || || || undefined
|-
| 007F || || || || || || undefined
|-
| 0080 - 00F8 || || || || || || Up transition (release or unpress key) (0080 for 0000, 00F8 for 0078)
|-
| 00F9 || || || || || || Last key code was bad (was sent in order to resynchronize)
|-
| 00FA || || || || || || Keyboard buffer overflow
|-
| 00FB || || || || || || (undefined, reserved for keyboard processor catastrophe)
|-
| 00FC || || || || || || Keyboard selftest failed
|-
| 00FD || || || || || || Power-up key stream start. Keys pressed or stuck at power-up will be sent between 00FD and 00FE.
|-
| 00FE || || || || || || Power-up key stream end
|-
| 00FF || || || || || || No key code defined
|-
| 0100 || 0007 || 0088 || 0070 || 0013 || || Intl 2 Hiragana/Katakana
|-
| 0101 || 0007 || 008A || 0079 || 0064 || || Intl 4 Henkan
|-
| 0102 || 0007 || 008B || 007B || 0067 || || Intl 5 Muhenkan
|-
| 0103 || 0007 || 0068 || 0064 || 0008 || F13 || F13
|-
| 0104 || 0007 || 0069 || 0065 || 0010 || F14 || F14
|-
| 0105 || 0007 || 006A || 0066 || 0018 || F15 || F15
|-
| 0180 - 0185 || || || || || || Up transition (release or unpress key) (0180 for 0100)
|}

== Function Reference ==

The following are brief descriptions of the functions covered in this article. See the SDK for details on each function call.

{| class="wikitable"
! Function
! Description
|-
| AskKeyMapDefault()
| Ask for a pointer to the current default keymap
|-
| CloseKeyMapHandle()
| Close a keymap handle (V50)
|-
| MapANSI()
| Encode an ANSI string into key codes
|-
| MapRawKey()
| Decode a raw key input event to an ANSI string
|-
| ObtainKeyMapInfo()
| Obtain information about a raw key (V51.7)
|-
| OpenKeyMapHandle()
| Open a keymap handle (V50)
|-
| ReleaseKeyMapInfo()
| Release info obtained from a keymap handle (V50)
|-
| SetKeyMapDefault()
| Set the current default keymap
|}

Migration Guide

2019-03-26T21:01:03Z

Frédéric Khannouf: /* Include Files */

== Introduction ==

In spite of being largely compatible with the classic API, there are a few rules that a programmer should be aware of when porting programs from the 68k-based AmigaOS 3.x to the new PowerPC-based AmigaOS 4. This document tries to outline the process and also point to a few potential traps and issues.

== Source Code Level ==

==== Include Files ====

Include files used to be a problematic issue under OS 3.x because there where a lot of different compilers, and most of them tended to use their own naming scheme and glue to bind to the operating system. The well-known SAS/C and StormC compiler systems used #pragma's for this purpose while gcc used inline functions or #define directives. AmigaOS 4 at the moment supports two compiler systems (GNU GCC and the vbcc package) and both use the same scheme for include files.

To use a library under AmigaOS 4, you simply include its proto file, in addition to any other file that may be required. For example, to use Intuition Windows and Screens, you would add the following to your program:

<syntaxhighlight>
#include <intuition/intuition.h>
#include <intuition/screens.h>
#include <proto/intuition.h>
</syntaxhighlight>

The proto file includes the required headers, which might depend on the compiler you are using. Just including the proto file will ensure maximum compatibility between different compilers.

A few preprocessor symbols influence the way that the system bindings are included. Table 1 summarizes these symbols. They are typically defined in a Makefile, although they may as well be put into #define directives. Don't worry if you don't understand everything in that table; things will become clearer further down this document.

{| class="wikitable"
! Symbol
! Meaning
|-
| __USE_INLINE__
| This symbol makes the protofile include an inline4 file as well. An inline4 file contains preprocessor macros for functions that resemble the classic way of calling system functions (i.e. functions as opposed to methods). Primarily intended for backward compatibility with older source code, or general compatibility.
|-
| __NOLIBBASE__
| Inhibits the definition of the library base associated with the proto file. Usually a proto file declares an extern symbol for the library base.
|-
| __USE_BASETYPE__
| If __NOLIBBASE__ is not defined, this symbol specifies whether the library base is declared with its "real" type (for example struct IntuitionBase for Intuition) or with the abstract base type for the class of resource (struct Library or struct Device). Only library implementors should use this symbol; normally, all library base structures are private and should not be examined. The default behavior is to declare all library bases as struct Library and all device bases as struct Device.
|-
| __NOGLOBALIFACE__
| Proto files for libraries that declare static global interfaces (like all "classic" libraries) normally also declare the interface pointer inside their proto file, unless this symbol is defined. Normally, you would only use this if you want to store the interface pointer elsewhere, for example in a library base.
|}

Table 1: Preprocessor symbols that control the proto file

Speaking of preprocessor symbols, the compiler defines a preprocessor symbol when targeting AmigaOS 4.x: __amigaos4__ and you can use this symbol for optional compilation of code.

==== Library Bases and Interface Pointers ====

Library bases should not normally be declared inside a source file. The proto file usually declares the required library base itself. If you want to do it anyway, you should define the preprocessor symbol __NOLIBBASE__ to prevent the proto file from doing it.

Contrary to the old system, AmigaOS 4 has a slightly different way of calling library functions. The old system used to call a library function by making a relative jump into a jump table located directly in front of the library base. AmigaOS 4 keeps these jump tables for backwards compatibility only - only 68k functions are still called this way. The new OS now keeps jump tables in a separate pointer called the "Interface Pointer", or short "interface". Basically an interface is a structure with a bit of housekeeping information and a lot of inline function pointers. A library may export more than one interface pointer (it usually exports at least two).

Almost all libraries export an interface by the name of "main". The exact type of this interface depends on the library. For example, exec.library will export a main interface of type "struct ExecIFace *" (Note that it would theoretically be possible for another library to export an interface of type "struct ExecIFace *").

Like the library bases formerly used to call library functions, by convention a global variable is used to make the ExecIFace pointer available to all functions in your program. The name of that variable is constructed by prepending the library base name ("Exec" in this example) with a capital I. Thus, the global struct ExecIFace * would be called IExec. Note that this is simply a convention introduced by the proto files. You do not need to even use a global interface pointer, as much as you don't need to use a global library pointer (neither now in AmigaOS 4, nor in AmigaOS 3.9 or earlier).

==== Type Consistency ====

The PowerPC architectural manual frequently uses the word "word" to signify a 32 bit quantity. However in classic AmigaOS, the types WORD and UWORD meant a 16 bit signed and unsigned quantity. Likewise, an 8 bit quantity used to be called BYTE or UBYTE and 32 bit "words" where called LONG and ULONG. No 64 bit quantity existed. To clean up the naming of base types, these types have all been deprecated for AmigaOS 4. The new types are consistently called int or uint followed by the number of bits, for example uint32 signifies a 32 bit unsigned quantity. Likewise, the typing has been extended to include a 64 bit quantity. Table 2 lists the new types and the "classic" types they replace. Note that the old types are still available through preprocessor defines, but should not be used anymore in new code.

{| class="wikitable"
! New Type
! Old Type
! Significance
|-
| int8
| BYTE
| 8 bit signed
|-
| uint8
| UBYTE
| 8 bit unsigned integer
|-
| int16
| WORD
| 16 bit signed
|-
| uint16
| UWORD
| 16 bit unsigned integer
|-
| int32
| LONG
| 32 bit signed
|-
| uint32
| ULONG
| 32 bit unsigned integer
|-
| int64
| None existed
| 64 bit signed
|-
| uint64
| None existed
| 64 bit unsigned integer
|-
| float32
| FLOAT
| 32 bit single-precision floating point number
|-
| float64
| DOUBLE
| 64 bit double-precision floating point number
|}

Table 2: New Base Types

== Programming Considerations ==

==== Library Initialization using libauto ====

System libraries may be opened automatically using the libauto link library. libauto can automatically open a number of system libraries (see [[#libauto_Libraries|libauto Libraries]] for a list of these libraries) and also set up their interface pointers. If you include the proto file in your program and link with libauto, the appropriate library will be all set up. For example, including <proto/intuition.h> will set up IntuitionBase and IIntuition automatically so that they are all set up when your program enters the main() function. The following example program opens a simple window, waits a bit then closes it again:

<syntaxhighlight>
#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>

int main()
{
struct Window *win = IIntuition->OpenWindowTags(NULL,
WA_Title, "Example Window",
WA_Width, 640,
WA_Height, 480,
TAG_END);

IDOS->Delay(150);

IIntuition->CloseWindow(win);

return 0;
}
</syntaxhighlight>

For the time being, ignore the way that functions are written (IIntuition->OpenWindowTags as opposed to a simple OpenWindowTags, we'll cover that later).

Save this program as windowtest.c and compile it with:

gcc -o windowtest windowtest.c -lauto

==== Manual Library Initialization ====

Libraries can also be initialized by hand. As with the old system, the function to do this is exec.library's OpenLibrary function. However, as we have hinted above, the library base is not the only requirement for using a library - you need to retrieve the interface pointer (or rather, all interface pointers you need) from the library to make use of it. On the classic system, opening for example intuition.library looked like this:

<syntaxhighlight>
IntuitionBase = (struct IntuitionBase *)OpenLibrary("intuition.library", 36);
if (IntuitionBase == NULL) PanicExit("Cannot open intuition library");

// ...
struct Window *win = OpenWindowTags(NULL, ...);
// ...

CloseWindow(win);
</syntaxhighlight>

Under AmigaOS 4, this will look like this:

<syntaxhighlight>
IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace *)IExec->GetInterface(
IntuitionBase, "main", 1, NULL);

if (IIntuition == NULL) {
PanicExit("Cannot obtain main interface from Intuition");
}

// ...
struct Window *win = IIntuition->OpenWindowTags(NULL, ...);
// ...

IExec->DropInterface((struct Interface *)IIntuition);
IExec->CloseLibrary(IntuitionBase);
</syntaxhighlight>

Changed passes have been marked in bold. As you can see, there are some obvious changes:

# All functions are prefixed by either IExec-> or IIntuition->.
# An additional variable, IIntuition is initialized.
# IntuitionBase is now a struct Library and no longer needs a typecast.

The new variable is called the "interface pointer". Note that when you call GetInterface, you need to pass in the library base from which you want to retrieve the interface pointer, its name ("main" in this case, as in almost all classic libraries) and a version number (1 is the base version). The last parameter is a pointer to a tag list; for defined tag items please consult the autodoc.

The interface pointer is needed to actually call the functions of a library (remember that the "original" jump table only contains 68k pointers). Thus, to call an Intuition function, you write "IIntution->OpenWindowTags" instead of a simple "OpenWindowTags". Note that there are ways around this; as we said in the introduction, using the preprocessor symbol __USE_INLINE__ will automatically include a file that contains a macro definition of the following type:

<syntaxhighlight>
#define OpenWindowTags(...) \
IIntuition->OpenWindowTags(__VA_ARGS__)
</syntaxhighlight>

This will both ensure compatibility with old source code, as well as allowing you to maintain different versions of your software.

==== Opening Devices ====

Opening a device also works largely the same as under OS 3.x. If a device doesn't export its own function table, like serial device, then there is no additional step required. If, on the other hand, the device does export its own function table, you need to retrieve the interface pointer just as you would retrieve the interface pointer from a library. For example, timer device is usually opened like this (error checking removed for clarity):

<syntaxhighlight>
struct MsgPort *TimerMP = IExec->AllocSysObject(ASOT_PORT, NULL);

struct TimeRequest *TimerIO = IExec->AllocSysObjectTags(AOST_IOREQUEST,
ASOIOR_Size, sizeof(struct TimeRequest),
ASOIOR_ReplyPort, TimerMP,
TAG_END);

IExec->OpenDevice(TIMERNAME, UNIT_MICROHZ, TimerIO, 0);

struct Library *TimerBase = (struct Library *)TimerIO->tr_node.io_Device;

struct TimerIFace *ITimer = (struct TimerIFace *)
IExec->GetInterface(TimerBase, "main", 1, NULL);

ITimer->GetSysTime(&tv);

if (!IExec->CheckIO(TimerIO))
IExec->AbortIO(TimerIO);

IExec->WaitIO(TimerIO);
IExec->DropInterface((struct Interface *)ITimer);
IExec->CloseDevice(TimerIO);
IExec->FreeSysObject(ASOT_IOREQUEST, TimerIO);
IExec->FreeSysObject(ASOT_PORT, TimerMP);
</syntaxhighlight>

As you can see, except for the initialization of the interface pointer, everything is the same. The AllocSysObject functions at the top are new to Exec V50, and fulfill the same function as AllocDosObject in DOS. Consult the autodoc for more info. Also note the timer.device structures have been renamed.

==== Calling Library Functions ====

We've basically covered this before already, but we'll review it here for completeness. A libraries interface pointer can be used to call the libraries functions. Thus, if you want to call an Exec function, you need to explicitly call the "method" from the interface.

You might wonder why we chose this path instead of simply providing stub functions. Well, for one thing if you do not like this kind of calling mechanism, you can completely isolate yourself from it by using the inline4 macro files. These "simulate" the use of "normal" functions, however, they come with the same issues as the preprocessor based inlines of the classic gcc, namely that - as preprocessor macros - they aren't aware of name spaces and scopes, and are blindly replaced on a textual basis. Thus, if you have for example a C++ class list that contains a member function AddHead, the preprocessor will most likely complain that you used a macro with the wrong number of arguments.

Likewise, it means that the name of a function needs to be unique across the whole system. The result are longer function names with redundant naming.

Finally, the interfaces allow for other things. For example, expansion library uses interfaces in a sort of object-oriented way - every PCI device on the bus is represented by a separate interface. That means that instead of repeating the PCI bus, device and function ID's as parameters every time, you can write something like:

<syntaxhighlight>
a = MyDevice->ReadConfigByte(PCI_INTERRUPT_LINE);
MyDevice->WriteConfigByte(PCI_INTERRUPT_LINE, a & 0x0F);
</syntaxhighlight>

The following chapter goes a bit deeper into the matter; you may skip it if you want, since ported classic programs will seldom need to make use of interfaces other than the basic initialization and cleanup tasks.

==== Interface Basics ====

Interfaces have a usage count. That count is implicitly incremented when you call GetInterface and decremented again on DropInterface. You can explicitly do that using the Obtain() and Release() method that all interfaces implement. You must do this if you intend to use the interface you obtained somewhere outside the context of your task. For example, consider an image loader library that returns a picture in the form of an interface. Suppose that this interface contains a Print() method that you can use to send the image to a printer. Quite naturally, this will take its time, so the program launches a subtask that takes care of that. The subtask would look something like that (some error handling removed for clarity):

<syntaxhighlight>
void print_task(struct PictureIFace *IPicture)
{
IPicture->Print(some_printer_description);
IPicture->Release();
}

// Somewhere else...
struct PictureIFace *IPicture = ILoader->Load("DH0:Backdrop.jpg");

// Pass the picture to the print spooler.
IPicture->Obtain(); // Add a reference so that it will not vanish too soon

// Create the spooler task. CreateTaskTags is new for V50.
// Note how you can now pass arguments to the created task.
if (IExec->CreateTaskTags("Printer Spooler",
SPOOLER_PRIORITY, print_task, SPOOLER_STACK_SIZE,
AT_Param, IPicture,
TAG_END) == NULL)
{
// Task creation failed.
IPicture->Release(); // Release the unused reference.

do_some_error_stuff();
}

// Spooler is running, we don't need our copy anymore.
IPicture->Release();
</syntaxhighlight>

What is happening here? The Load() method would create the IPicture interface, thus giving us a fully usable IPicture interface with one reference. Since we want to pass it to a subtask, we do add another reference to the internal counter (increasing it to two) and pass it on down to the spooler task. After that task is running, we simply mark our copy as unused by calling Release() on it (we're now back at one again).

When the spooler is done, it will call Release() itself again, thus bringing the counter to zero. If the usage counter of an interface ever reaches zero, this indicates to the system that the interface is done with, and will trigger the interface's destruction.

== Calling 68K Functions ==

Some system code as well as some application code might still be 68k based. Usually an application programmer doesn't need to worry about this, though as most of the details are handled internally by the system. Typical places where PowerPC to 68k transitions take place are:

# 68k libraries
# 68k hook functions
# 68k interrupts

==== 68k Library Entries ====

For this discussion we assume that we have a disk based library called "foo.library" that is written in 68k code. Previously we have said that library calls always go through an interface - in most cases called "main" - but obviously the writer of the 68k library was unaware of this mechanism.

In order to present a unified calling mechanism to the programmer, 68k libraries are called through the same interfaces as a PowerPC library would. Since the original library doesn't provide this interface, a disk-resident stub library will do that. In our case, this library would be called "foo.l.main". The 'l' comes from the first letter of the resource type ("library" in this case), and the "main" is the name of the interface it provides. Thus, the "foo.l.main" stub will provide the interface "main" for "foo.library". If you call ObtainInterface() on a 68k library, the system will automatically scan its library search path for the file "foo.l.main" and if found, will try to open it and obtain the interface.

While this may look strange at first sight, it offers the possibility to migrate "foo.library" to PowerPC later on without the need to even recompile the application(s) using it. Furthermore, for a transition the "foo.l.main" interface may contain a few "real" PowerPC functions - normally it is composed from stub functions that call the 68k emulator.

The downside is that (at the time of writing) the "foo.l.main" library will not be created automatically. There are tools available in the SDK to build it from an SFD file, though. This process is described in a different document.

==== 68k Hook Functions ====

Hook functions in general are completely transparent when it comes to PowerPC vs. 68k issues. You must not call a hook function directly, though - doing this used to be legal in the pre-4.0 era, but will result in an ISI exception for AmigaOS 4.

Hook functions must be called through Utility's CallHookPkt function. Invoking a hook this way will make sure that the appropriate measures are met - either by invoking the emulator, or by a real jump into the code.

==== 68k Interrupts ====

As with hook functions, interrupts are handled completely transparently. When an interrupt is added to the system, a few checks are done and the interrupt's ln_Type field may be modified. This is done to ensure minimum latency when the interrupt occurs. The consequence is that you may not change the is_Code field of an interrupt node without removing and re-adding it to the system first.

==== Calling The Emulator Directly ====

In rare cases you might want to directly call the 68k emulator to execute 68k code. Exec provides the function Emulate for this purpose. Emulate can be called with an implicit register mapping and an arbitrary address. For more information on Emulate please refer to its autodoc.

== Other Programming Considerations ==

==== General Hook Functions ====

Hook functions used to be called with a specific mapping of 68k registers. Quite naturally, there are no 68k registers on a PowerPC machine, so the programmer needs to be a bit careful when writing a hook function.

CallHookPkt, or its vararg version CallHook, will always adhere to the PowerPC SysV ABI, and therefore the order of the parameters in the called function is important (it was always to be considered bad style to rearrange the parameters of a hook function, but possible through the explicit declaration of register mappings).

A hook function should always look like this:

<syntaxhighlight>
uint32 HookFunction(struct Hook *hook, APTR object, APTR message);
</syntaxhighlight>

The first argument, hook, points to the hook with which this function was invoked. The second paramter, objec, is a generic 'target' for the oeration, and depends on the context that this hook is being called in. The final argument, message, is a pointer to a message package whose layout also depends on the hook context.

Hook functions need to have the VARARGS68K tag. The next chapter will describe what that means.

==== Varargs ====

Although frequently used, the following code is highly system- and compiler-dependent:

<syntaxhighlight>
void somefunc(int messageid, ...)
{
char *message = (char *)(&messageid + 1);
if (messageid == some_id)
{
int x = *(int *)message; message += sizeof(int);
int y = *(int *)message; message += sizeof(int);
// ...
</syntaxhighlight>

This code assumes that arguments are put on the stack in sequential order, which happens to be true by chance but cannot be counted on. On AmigaOS 4.0 onwards, the system uses the PowerPC SystemV ABI, which doesn't allow for such tricks. ANSI-C defines a specific mechanism for variable number of arguments functions, namely va_start(), va_end() and va_arg(). . Under all normal circumstances, these must be used on AmigaOS 4.

The only legal way to express the above code is:

<syntaxhighlight>
#include <stdarg.h>
void somefunc(int messageid, ...)
{
va_list ap;
va_start(ap, messageid);
if (messageid == some_id)
{
uint16 x = va_arg(ap, uint16);
uint16 y = va_arg(ap, uint16);
// ...
}

va_end(ap);
}
</syntaxhighlight>

There is one exception to this rule, though. Under certain circumstances it is necessary to be able to use these stack varargs because of compatibility. The AmigaOS 4 compilers must support a means to specify this as a special linkage parameter for a function. The SDK include file amiga_compiler.h encapsulates the details in a common macro VARARGS68K. A function declared with this tag is handled differently by the compiler, so that the calling method outlined at the beginning of this chapter works. The tag may be used both to declare a function within your program as well as declaring a function outside your program. The former is required for example for hook functions, while the latter may be required for legacy code.

Such a function still needs to access the parameters in a special way. The first argument (messageid in this example) still is passed in a register according to the ABI specs. The following fragment shows how to handle this case.

<syntaxhighlight>
#include <stdarg.h>

void somefunc(int messageid, ...) VARARGS68K;

void somefunc(int messageid, ...)
{
va_list ap;
va_startlinear(ap, messageid);

char *message = va_getlinearva(ap, char *);

if (messageid == some_id)
{
uint16 x = *(uint16 *)message; message += 4;
uint16 y = *(uint16 *)message; message += 4;
// ...
}

va_end(ap);
}
</syntaxhighlight>

Note that parameters passed in this way are always longword-aligned. On the 68k this used to be different depending on the compiler - another reason why you should avoid this kind of calling mechanism.

== Memory ==

==== The MEMF_PUBLIC flag ====

The memory subsystem of AmigaOS 4 has seen a radical overhaul. Although the API stays mostly the same, there are a few things to look out for when porting old code, as well as when writing new code.

A general rule of thumb is: Don't use it. There is usually no reason why you should be using MEMF_PUBLIC memory. On AmigaOS 3.9 and earlier you had to allocate e.g. Messages and Message Ports in public memory; this is no longer needed under AmigaOS 4 - instead use the MEMF_SHARED flag. The MEMF_SHARED flag shares a lot of the properties that its public counterpart has, but is much more "friendly" to the system.

For more information about MEMF_PUBLIC see [[Obsolete_Exec_Memory_Allocation|Obsolete Exec Memory Allocation]].

==== Visible Changes in the Memory Subsystem ====

Most of the changes done to the memory system under AmigaOS 4 is done "under the hood" and invisible to the application programmer. However, a few changes may affect the programmer, and therefore need to be taken care of.

First of all, memory is virtualized. That means that any access to unallocated memory will invariably result in an abnormal termination of your program. Like the Enforcer in earlier versions of the system, the AmigaOS 4 memory system does not tolerate any such access. Contrary to the Enforcer, however, such illegal accesses are fatal. AmigaOS 4 software must not access illegal memory areas.

Memory will, as a rule, go away at the very moment that it is freed. Being inside a forbid state does not allow you to access memory after freeing it.

Also, virtualized memory means that the physical address where memory is located does not necessarily match the virtual address that you are using. While that doesn't have any impact in normal operation, it is something that device driver writers will have to take care of - there are calls in Exec that map physical to virtual and vice versa. In addition, memory that appears continuous to your application (which uses virtual addresses) need not be continuous in physical memory.

In the past some clever programmers where scanning Exec's memory lists, in spite of a comment that clearly marked them as "private". This will no longer be tolerated in AmigaOS. In fact, chances are that the memory lists are uninitialized, since the traditional memory allocation schemes are in the process of being phased out at the time of writing in favor of a new and much faster memory allocation.

As we have already mentioned, there are some new memory flags for application programmers. MEMF_SHARED is one of them, the semantics of which have already been described above. Another one of these is MEMF_EXECUTABLE. Normally, executable code may not be placed into an arbitrary section of memory. If you intend to generate code dynamically, you must use MEMF_EXECUTABLE to allocate the memory. Also note that the code section of your program is write protected, so self-modifying is not possible unless you allocate a piece of MEMF_EXECUTABLE memory and generate your code there.

Please refer to [[Exec_Memory_Allocation|Exec Memory Allocation]] for more information.

== Known Incompatibilities ==

Due to the migration to PowerPC and other changes in the system itself, there are a few known incompatibilities with old software and/or source code that may cause trouble. This is true both for porting software to run on AmigaOS 4 natively as well as binary 68k legacy programs. The following list tries to outline the known issues and tries to list workarounds.

Most of these issues are caused by inappropriate programming, for example exploiting undocumented or internal features. In general, if you strictly adhere to the programming guidelines your program should work unmodified, but some things that where tolerated under OS 3.9 and earlier will no longer work.

* Assembler programmers should NOT simply check the zero flag if the function is documented to return 0 or non-null. For example, if you open a device it is NOT sufficient to check the zero flag to find out if the open was successful or not. This assumes that the return value is set up at the very end of the function and that no operation had any influence on it; furthermore, since the emulator "only" calls native code and passes the return value to your 68k function, the flag bits are not affected. This was never supposed to work, and will no longer work. A simple "cmp.l #0,d0" or "tst.l d0" will be sufficient.

* Access to any unmapped/unallocated memory fill most likely result in a fatal crash. It is not OK to "temporarily store" results somewhere because your application "happens to know" that the area is free. Likewise, NULL pointer access will invariably result in a crash. The user will be able to click "continue" in the Grim Reaper window that will pop up, though, but the result will be undefined.

* It has never been documented where and how (if at all) AllocVec stores the size of the block it has allocated. Therefore, it has always been illegal to try to access the four bytes before the actual allocation to find the size of the block. Code that will use this "feature" will no longer work, since AmigaOS 4's AllocVec does not necessarily put anything there.

* Public data does not belong on the stack. If you want to send a message, allocate it with AllocSysObjectTags() using the ASOT_MESSAGE type. The following code is broken:
<syntaxhighlight>
void foo(void)
{
struct Message msg;
// ...
IExec->PutMsg(port, &msg);
}
</syntaxhighlight>

* Locale library uses new country/language names. All language names are represented by their English name because it eliminates the need for special characters that the file system may not support or that require a special font to display.

* Do not copy font flags. Font flags carry a specific meaning that may or may not be specific to a certain font. For example, setting the FSF_ANTIALIASED flag on a bitmap font may cause unpredictable behavior.

* It never was, and never will be, legal to access memory after you have freed it. No matter if you are in Forbid() state or not, a program MUST NOT access memory after it called FreeMem() or any other function that frees memory. Doing so will invariably cause a crash of your program. It is not OK to assume that memory will stay available up to the next Permit(). Freeing memory will most likely trigger immediate un-mapping of associated memory pages, meaning that any further access will result in a Data Storage (DSI) exception. The same holds true for executable memory that is freed due to a FreeVec or UnLoadSeg. The next instruction to be executed will no longer be there because the memory has vanished, resulting in an ISI exception.

== libauto Libraries ==

The following global variables are automatically handled by the current libauto. Note that the entries in bold are automatically supplied by your C library's startup code and are always available (clib2 does not provide UtilityBase and IUtility):

{| class="wikitable"
! Library
! Interface(s)
|-
| AmigaGuideBase
| IAmigaGuide
|-
| ApplicationBase
| IApplication, IPrefsObjects
|-
| ARexxBase
| IARexx
|-
| AslBase
| IAsl
|-
| BevelBase
| IBevel
|-
| BitMapBase
| IBitMap
|-
| SocketBase
| ISocket
|-
| ButtonBase
| IButton
|-
| CheckBoxBase
| ICheckBox
|-
| ChooserBase
| IChooser
|-
| ClickTabBase
| IClickTab
|-
| ColorWheelBase
| IColorWheel
|-
| CxBase
| ICommodities
|-
| DataTypesBase
| IDataTypes
|-
| DateBrowserBase
| IDateBrowser
|-
| DiskfontBase
| IDiskfont
|-
| DOSBase
| '''IDOS'''
|-
| DrawListBase
| IDrawList
|-
| ElfBase
| IElf
|-
| ExecBase
| '''IExec''', IDebug
|-
| ExpansionBase
| IExpansion
|-
| FillerBase
| IFiller
|-
| FuelGaugeBase
| IFuelGauge
|-
| GadToolsBase
| IGadTools
|-
| GetColorBase
| IGetColor
|-
| GetFileBase
| IGetFile
|-
| GetFontBase
| IGetFont
|-
| GetScreenModeBase
| IGetScreenMode
|-
| GlyphBase
| IGlyph
|-
| GfxBase
| IGraphics
|-
| IconBase
| IIcon
|-
| IFFParseBase
| IIFFParse
|-
| InputBase
| IInput
|-
| IntegerBase
| IInteger
|-
| IntuitionBase
| IIntuition
|-
| KeymapBase
| IKeymap
|-
| LabelBase
| ILabel
|-
| LayersBase
| ILayers
|-
| LayoutBase
| ILayout
|-
| ListBrowserBase
| IListBrowser
|-
| LocaleBase
| '''ILocale'''
|-
| LowLevelBase
| ILowLevel
|-
| MiniGLBase
| IMiniGL
|-
| PaletteBase
| IPalette
|-
| PenMapBase
| IPenMap
|-
| P96Base
| IP96
|-
| PictureBase
| IPicture
|-
| PopupMenuBase
| IPopupMenu
|-
| RadioButtonBase
| IRadioButton
|-
| RequesterBase
| IRequester
|-
| RexxSysBase
| IRexxSys
|-
| ScreenBlanker
| IScreenBlanker
|-
| ScrollerBase
| IScroller
|-
| SketchBoardBase
| ISketchBoard
|-
| SliderBase
| ISlider
|-
| SpaceBase
| ISpace
|-
| SpeedBarBase
| ISpeedBar
|-
| StringBase
| IString
|-
| TextClipBase
| ITextClip
|-
| TextEditorBase
| ITextEditor
|-
| TimerBase
| ITimer
|-
| TimesyncBase
| ITimesync
|-
| TimezoneBase
| ITimezone
|-
| UserGroupBase
| IUserGroup
|-
| UtilityBase
| '''IUtility'''
|-
| VirtualBase
| IVirtual
|-
| WorkbenchBase
| IWorkbench
|-
| WindowBase
| IWindow
|-
| xadMasterBase
| IxadMaster
|}

Exec Messages and Ports

2019-03-26T13:22:24Z

Frédéric Khannouf: /* Replying */

== Exec Messages and Ports ==

For inter-process communication, Exec provides a consistent, high-performance mechanism of messages and ports. This mechanism is used to pass message structures of arbitrary sizes from task to task, interrupt to task, or task to software interrupt. In addition, messages are often used to coordinate operations between cooperating tasks. This section describes many of the details of using messages and ports that the casual Amiga programmer won't need. See [[Introduction_to_Exec|Introduction to Exec]] for a general introduction to using messages and ports.

A ''message'' data structure has two parts: system linkage and message body. The system linkage is used by Exec to attach a given message to its destination. The message body contains the actual data of interest. The message body is any arbitrary data up to 64K bytes in size. The message body data can include pointers to other data blocks of any size.

Messages are always sent to a predetermined destination ''port''. At a port, incoming messages are queued in a first-in-first-out (FIFO) order. There are no system restrictions on the number of ports or the number of messages that may be queued to a port (other than the amount of available system memory).

Messages are always queued by ''reference'', i.e., by a pointer to the message. For performance reasons message copying is not performed. In essence, a message between two tasks is a temporary license for the receiving task to use a portion of the memory space of the sending task; that portion being the message itself. This means that if task A sends a message to task B, the message is still part of the task A context. Task A, however, should not access the message until it has been ''replied''; that is, until task B has sent the message back, using the ReplyMsg() function. This technique of message exchange imposes important restrictions on message access.

== Message Ports ==

Message ports are rendezvous points at which messages are collected. A port may contain any number of outstanding messages from many different originators. When a message arrives at a port, the message is appended to the end of the list of messages for that port, and a pre-specified arrival action is invoked. This action may do nothing, or it may cause a predefined task signal or software interrupt (see [[Exec_Interrupts|Exec Interrupts]]).

Like many Exec structures, ports may be given a symbolic name. Such names are particularly useful for tasks that must rendezvous with dynamically created ports. They are also useful for debugging purposes.

A message port consists of a MsgPort structure as defined in the <exec/ports.h> and <exec/ports.i> include files. The C structure for a port is as follows:

<syntaxhighlight>
struct MsgPort {
struct Node mp_Node;
UBYTE mp_Flags;
UBYTE mp_SigBit;
struct Task *mp_SigTask;
struct List mp_MsgList;
};
</syntaxhighlight>

; mp_Node
: is a standard Node structure. This is useful for tasks that might want to rendezvous with a particular message port by name.

; mp_FLags
: are used to indicate message arrival actions. See the explanation below.

; mp_SigBit
: is the signal bit ''number'' when a port is used with the task signal arrival action.

; mp_SigTask
: is a pointer to the task to be signaled. If a software interrupt arrival action is specified, this is a pointer to the interrupt structure.

; mp_MsgList
: is the list header for all messages queued to this port. (See [[Exec_Lists_and_Queues|Exec Lists and Queues]]).

The mp_Flags field contains a subfield indicated by the PF_ACTION mask. This sub-field specifies the message arrival action that occurs when a port receives a new message.

The possibilities are as follows:

; PA_SIGNAL
: This flag tells Exec to signal the mp_SigTask using signal number mp_SigBit on the arrival of a new message. Every time a message is put to the port another signal will occur regardless of how many messages have been queued to the port.

; PA_SOFTINT
: This flag tells Exec to Cause() a software interrupt when a message arrives at the port. In this case, the mp_SigTask field must contain a pointer to a struct Interrupt rather than a Task pointer. The software interrupt will be Caused every time a message is received.

; PA_IGNORE
: This flag tells Exec to perform no operation other than queuing the message. This action is often used to stop signaling or software interrupts without disturbing the contents of the mp_SigTask field.

It is important to realize that a port's arrival action will occur for each new message queued, and that there is not a one-to-one correspondence between messages and signals. Task signals are only single-bit flags so there is no record of how many times a particular signal occurred. There may be many messages queued and only a single task signal; sometimes however there may be a signal, but no messages. All of this has certain implications when designing code that deals with these actions. Your code should not depend on receiving a signal for every message at your port. All of this is also true for software interrupts.

=== Creating a Message Port ===

To create a new message port use AllocSysObject() with an object type of ASOT_PORT. If you want to make the port ''public'', you will need to use the ASOPORT_Name tag. Don't make a port public when it is not necessary for it to be so.

Prior to V50 of the operating system, functions such as CreatePort() and CreateMsgPort() were often used. Some older applications may even have created their own static message ports by hand. Although all of the older methods still function for backwards compatibility, they should no longer be used.

Using dynamic message ports with ASOT_PORT is the only way to ensure your applications will remain compatible and its message ports automatically freed by the system when required.

=== Deleting a Message Port ===

Before a message port is deleted, all outstanding messages from other tasks must be returned. This is done by getting and replying to all messages at the port until message queue is empty. Of course, there is no need to reply to messages owned by the current task (the task performing the port deletion). Public ports must be removed from the system properly before deallocation. If a signal was allocated for the message port, it must also be freed. FreeSysObject() handles all of this automatically.

Prior to V50 of the operating system, message ports must be freed using the correct corresponding function such as DeletePort() or DeleteMsgPort(). The FreeSysObject() function must only be used on ports which were allocated with AllocSysObject().

=== How to Rendezvous at a Message Port ===

The FindPort() function provides a means of finding the address of a public port given its symbolic name. For example, FindPort("Griffin") will return either the address of the message port named "Griffin" or NULL indicating that no such public port exists. Since FindPort() does not do any arbitration over access to public ports, the usage of FindPort() must be protected with Forbid()/Permit(). Names should be unique to prevent collisions among multiple applications. It is a good idea to use your application name as a prefix for your port name. FindPort() does not arbitrate for access to the port list. The owner of a port might remove it at any time. For these reasons a Forbid()/Permit() pair is required for the use of FindPort(). The port address can no longer be regarded as being valid after Permit() unless your application knows that the port cannot go away (for example, if your application created the port).

The following is an example of how to safely put a message to a specific port:

<syntaxhighlight>
#include <exec/types.h>
#include <exec/ports.h>

BOOL SafePutToPort(struct Message *message, CONST_STRPTR portname)
{
IExec->Forbid();

struct MsgPort *port = IExec->FindPort(portname);
if (port != NULL)
IExec->PutMsg(port,message);

IExec->Permit();

return(port ? TRUE : FALSE); /* If FALSE, the port was not found */

/* Once we've done a Permit(), the port might go away and leave us with
an invalid port address. So we return just a BOOL to indicate whether
the message has been sent or not. */
}
</syntaxhighlight>

== Messages ==

As mentioned earlier, a message contains both system header information and the actual message content. The system header is of the Message form defined in <exec/ports.h>. This structure is as follows:

<syntaxhighlight>
struct Message {
struct Node mn_Node;
struct MsgPort *mn_ReplyPort;
UWORD mn_Length;
};
</syntaxhighlight>

; mn_Node
: is a standard Node structure used for port linkage.

; mn_ReplyPort
: is used to indicate a port to which this message will be returned when a reply is necessary.

; mn_Length
: indicates the total length of the message, including the Message structure itself.

This structure is always attached to the head of all messages. For example, if you want a message structure that contains the ''x'' and ''y'' coordinates of a point on the screen, you could define it as follows:

<syntaxhighlight>
struct XYMessage {
struct Message xy_Msg;
UWORD xy_X;
UWORD xy_Y;
}
</syntaxhighlight>

For this structure, the mn_Length field should be set to sizeof(struct XYMessage).

=== Creating a Message ===

Messages are allocated using AllocSysObject() with an object type of ASOT_MESSAGE. The ASOMSG_ReplyPort tag is set to the reply port if desired. Some messages may be sent in one direction in which case the ASOMSG_ReplyPort tag is not used. The size of the message is indicated with ASOMSG_Length and includes the size of the payload.

<syntaxhighlight>
struct XYMessage xymsg = IExec->AllocSysObjectTags(ASOT_MESSAGE,
ASOMSG_Size, sizeof(struct XYMessage),
ASOMSG_ReplyPort, replyPort,
TAG_END);
</syntaxhighlight>

=== Deleting a Message ===

Messages are freed using FreeSysObject(). Programmers should be careful not to free a message which is still in use or queues in a message port.

=== Putting a Message ===

A message is delivered to a given destination port with the PutMsg() function. The message is queued to the port, and that port's arrival action is invoked. If the action specifies a task signal or a software interrupt, the originating task may temporarily lose the processor while the destination processes the message. If a reply to the message is required, the mn_ReplyPort field must be set up prior to the call to PutMsg().

Here is a code fragment for putting a message to a public port. A complete example is at the end of the article.

<syntaxhighlight>
#include <exec/types.h>
#include <exec/memory.h>
#include <exec/ports.h>
#include <libraries/dos.h>

BOOL SafePutToPort(struct Message *, CONST_STRPTR);

struct XYMessage {
struct Message xy_Msg;
uint16 xy_X;
uint16 xy_Y;
};

int main()
{
struct MsgPort *xyport, *xyreplyport;
struct XYMessage *msg;
BOOL foundport;

/* Allocate the message we're going to send. */
struct XYMessage *xymsg = IExec->AllocSysObjectTags(ASOT_MESSAGE,
ASOMSG_Size, sizeof(struct XYMessage),
TAG_END);

if (xymsg != NULL)
{
/* The replyport we'll use to get response */
if (xyreplyport = IExec->AllocSysObject(ASOT_PORT, NULL)) {

xymsg->xy_Msg.mn_ReplyPort = xyreplyport;
xymsg->xy_X = 10;
xymsg->xy_Y = 20;

/* Now try to send that message to a public port named "xyport".
* If foundport eq 0, the port isn't out there.
*/
if (foundport = SafePutToPort((struct Message *)xymsg, "xyport"))
{

. . . /* Now let's wait till the someone responds... */

}
else IDOS->Printf("Couldn't find 'xyport'\n");

IExec->FreeSysObject(ASOT_PORT, xyreplyport);
else IDOS->Printf("Couldn't create message port\n");

IExec->FreeSysObject(ASOT_MESSAGE, xymsg);
}
else IDOS->Printf("Couldn't get memory for xymessage\n");

return 0;
}
</syntaxhighlight>

=== Waiting for a Message ===

A task may go to sleep waiting for a message to arrive at one or more ports. This technique is widely used on the Amiga as a general form of event notification. For example, it is used extensively by tasks for I/O request completion.

The MsgPort.mp_SigTask field contains the address of the task to be signaled and mp_SigBit contains a preallocated signal number (as described in [[Exec_Tasks|Exec Tasks]]).

You can call the WaitPort() function to wait for a message to arrive at a port. This function will return the first message (it may not be the only) queued to a port. Note that your application must still call GetMsg() to remove the message from the port. If the port is empty, your task will go to sleep waiting for the first message. If the port is not empty, your task will not go to sleep. It is possible to receive a signal for a port without a message being present yet. The code processing the messages should be able to handle this. The following code illustrates WaitPort().

<syntaxhighlight>
struct MsgPort *xyport = IExec->AllocSysObjectTags(ASOT_PORT,
ASOPORT_Name, "xyport",
TAG_END);

if (xyport == NULL)
{
IDOS->Printf("Couldn't create xyport\n");
return RETURN_FAIL;
}

struct XYMessage *xy_msg = IExec->WaitPort(xyport); /* go to sleep until message arrives */
</syntaxhighlight>

A more general form of waiting for a message involves the use of the Wait() function (see [[Exec_Signals|Exec Signals]]). This function waits for task event signals directly. If the signal assigned to the message port occurs, the task will awaken. Using the Wait() function is more general because you can wait for more than one signal. By combining the signal bits from each port into one mask for the Wait() function, a loop can be set up to process all messages at all ports.

Here's an example using Wait():

<syntaxhighlight>
struct XYMessage *xy_msg;
BOOL ABORT = FALSE;

struct MsgPort *xyport = IExec->AllocSysObjectTags(ASOT_PORT,
ASOPORT_Name, "xyport",
TAG_END);

if (xyport != NULL)
{
uint32 portsig = 1 << xyport->mp_SigBit;
uint32 usersig = SIGBREAKF_CTRL_C; /* User can break with CTRL-C. */
for (;;)
{
uint32 signal = IExec->Wait(portsig | usersig); /* Sleep till someone signals. */

if (signal & portsig) /* Got a signal at the msgport. */
{ . . .
}
if (signal & usersig) /* Got a signal from the user. */
{
ABORT = TRUE; /* Time to clean up. */
. . .
}
if (ABORT) break;
}
IExec->FreeSysObject(ASOT_PORT, xyport);
}
else IDOS->Printf("Couldn't create xyport\n");
</syntaxhighlight>

{{Note|text=WaitPort() only returns a pointer to the first message in a port. It does not actually remove the message from the port queue.|title=WaitPort() Does Not Remove A Message}}

=== Getting a Message ===

Messages are usually removed from ports with the GetMsg() function. This function removes the next message at the head of the port queue and returns a pointer to it. If there are no messages in a port, this function returns a zero.

The example below illustrates the use of GetMsg() to print the contents of all messages in a port:

<syntaxhighlight>
while (xymsg = IExec->GetMsg(xyport))
IDOS->Printf("x=%ld y=%ld\n", xymsg->xy_X, xymsg->xy_Y);
</syntaxhighlight>

Certain messages may be more important than others. Because ports impose FIFO ordering, these important messages may get queued behind other messages regardless of their priority. If it is necessary to recognize more important messages, it is easiest to create another port for these special messages.

=== Replying ===

When the operations associated with receiving a new message are finished, it is usually necessary to send the message back to the originator. The receiver replies the message by returning it to the originator using the ReplyMsg() function. This is important because it notifies the originator that the message can be reused or deallocated.

The ReplyMsg() function serves this purpose. It returns the message to the port specified in the mn_ReplyPort field of the message. If this field is zero, no reply is returned.

The previous example can be enhanced to reply to each of its messages:

<syntaxhighlight>
while (xymsg = IExec->GetMsg(xyport)) {
IDOS->Printf("x=%ld y=%ld\n", xymsg->xy_X, xymsg->xy_Y);
IExec->ReplyMsg(xymsg);
}
</syntaxhighlight>

Notice that the reply does not occur until ''after'' the message values have been used.

Often the operations associated with receiving a message involve returning ''results'' to the originator. Typically this is done within the message itself. The receiver places the results in fields defined (or perhaps reused) within the message body before replying the message back to the originator. Receipt of the replied message at the originator reply port indicates it is once again safe for the originator to use or change the values found within the message.

The following are two short example tasks that communicate by sending, waiting for and replying to messages. Run these two programs together.

==== Port1.c ====

<syntaxhighlight>
// port1.c - port and message example, run at the same time as port2.c

#include <exec/types.h>
#include <exec/ports.h>
#include <dos/dos.h>
#include <proto/exec.h>
#include <proto/dos.h>

struct XYMessage {
struct Message xym_Msg;
int16 xy_X;
int16 xy_Y;
};

int main()
{
BOOL ABORT = FALSE;

struct MsgPort *xyport = IExec->AllocSysObjectTags(ASOT_PORT,
ASOPORT_Name, "xyport",
TAG_END);

if (xyport != NULL)
{
uint32 portsig = 1U << xyport->mp_SigBit; /* Give user a `break' signal. */
uint32 usersig = SIGBREAKF_CTRL_C;

IDOS->Printf("Start port2 in another shell. CTRL-C here when done.\n");
do
{ /* port1 will wait forever and reply */
uint32 signal = IExec->Wait(portsig | usersig); /* to messages, until the user breaks. */
struct XYMessage *xymsg = 0;

/* Since we only have one port that might get messages we */
if (signal & portsig) /* have to reply to, it is not really necessary to test for */
{ /* the portsignal. If there is not message at the port, xymsg */

while(xymsg = (struct XYMessage *)IExec->GetMsg(xyport)) /* simply will be NULL. */
{
IDOS->Printf("port1 received: x = %d y = %d\n", xymsg->xy_X, xymsg->xy_Y);

xymsg->xy_X += 50; /* Since we have not replied yet to the owner of */
xymsg->xy_Y += 50; /* xymsg, we can change the data contents of xymsg. */

IDOS->Printf("port1 replying with: x = %d y = %d\n", xymsg->xy_X, xymsg->xy_Y);
IExec->ReplyMsg((struct Message *)xymsg);
}
}

if (signal & usersig) /* The user wants to abort. */
{
while(xymsg = (struct XYMessage *)IExec->GetMsg(xyport)) /* Make sure port is empty. */
IExec->ReplyMsg((struct Message *)xymsg);
ABORT = TRUE;
}
}
while (ABORT == FALSE);
IExec->FreeSysObject(ASOT_PORT, xyport);
}
else IDOS->Printf("Couldn't create 'xyport'\n");
return 0;
}
</syntaxhighlight>

==== Port2.c ====

<syntaxhighlight>
// port2.c - port and message example, run at the same time as port1.c

#include <exec/types.h>
#include <exec/ports.h>
#include <exec/memory.h>
#include <dos/dos.h>
#include <proto/exec.h>
#include <proto/dos.h>

BOOL SafePutToPort(struct Message *, CONST_STRPTR);

struct XYMessage {
struct Message xy_Msg;
int16 xy_X;
int16 xy_Y;
};

int main()
{
struct MsgPort *xyreplyport = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END);

if (xyreplyport != NULL)
{
struct XYMessage *reply = NULL;

struct XYMessage *xymsg = IExec->AllocSysObjectTags(ASOT_MESSAGE,
ASOMSG_Size, sizeof(struct XYMessage),
ASOMSG_ReplyPort, xyreplyport,
TAG_END);

if (xymsg != NULL)
{
xymsg->xy_X = 10; /* our special message information. */
xymsg->xy_Y = 20;

IDOS->Printf("Sending to port1: x = %d y = %d\n", xymsg->xy_X, xymsg->xy_Y);

/* port2 will simply try to put */
if (SafePutToPort((struct Message *)xymsg, "xyport")) /* one message to port1 wait for */
{ /* the reply, and then exit */
IExec->WaitPort(xyreplyport);
if (reply = (struct XYMessage *)IExec->GetMsg(xyreplyport))
IDOS->Printf("Reply contains: x = %d y = %d\n", /* We don't ReplyMsg since */
xymsg->xy_X, xymsg->xy_Y); /* WE initiated the message. */

/* Since we only use this private port for receiving replies, and we sent */
/* only one and got one reply there is no need to cleanup. For a public port, */
/* or if you pass a pointer to the port to another process, it is a very good */
/* habit to always handle all messages at the port before you delete it. */
}
else IDOS->Printf("Can't find 'xyport'; start port1 in a separate shell\n");
IExec->FreeSysObject(ASOT_Message, xymsg);
}
else IDOS->Printf("Couldn't get memory\n");
IExec->FreeSysObject(ASOT_PORT, xyreplyport);
}
else IDOS->Printf("Couldn't create xyreplyport\n");
return 0;
}

BOOL SafePutToPort(struct Message *message, CONST_STRPTR portname)
{
IExec->Forbid();
struct MsgPort *port = FindPort(portname);
if (port != NULL) IExec->PutMsg(port, message);
IExec->Permit();
return(port ? TRUE : FALSE); /* FALSE if the port was not found */

/* Once we've done a Permit(), the port might go away and leave us with an invalid port */
} /* address. So we return just a BOOL to indicate whether the message has been sent or not. */
</syntaxhighlight>

== Function Reference ==

The following chart gives a brief description of the Exec functions that control inter-task communication with messages and ports. See the SDK for details about each call.

{| class="wikitable"
! Function
! Description
|-
| AddPort()
| Add a public message port to the system list.
|-
| AllocSysObject(ASOT_PORT)
| Allocate and initialize a new message port.
|-
| FindPort()
| Find a public message port in the system list.
|-
| FreeSysObject(ASOT_PORT)
| Free a message port.
|-
| GetMsg()
| Get next message from the message port.
|-
| PutMsg()
| Put a message to a message port.
|-
| RemPort()
| Remove a message port from the system list.
|-
| ReplyMsg()
| Reply to a message on its reply port.
|}

Executing External Programs

2018-12-16T00:17:09Z

Frédéric Khannouf: /* The System Function */

= Executing External Programs =

The Amiga operating system provides flexible methods of launching programs from an application. The System() function is more flexible and powerful than the deprecated Execute() function. Improvements to the con-handler, CON:, allow programs to create "auto con" windows, which are console windows that will only appear if input is requested from or output is sent to that console.

== The System Function ==

System() spawns a shell process to execute the command line which is passed to System() as an argument. The shell parses the command-line normally, just like command-lines typed directly into the shell's console. If it can, System() will pass the current path and directory to the programs it launches.

The System() function can execute external commands either synchronously or asynchronously. When System() is used synchronously, control returns to the calling program after the external program has completed. In this case, System() returns the external program's return code, or a -1 if the command could not be found or run. On the other hand, when System() initiates a program asynchronously, the program is no longer a concern for the caller. The operating system will take care of the cleanup. This is extremely useful for an application that must start up multiple programs on user demand, such as a hot key commodity. By default, System() starts programs synchronously. To launch a program asynchronously, use the SYS_Asynch tag with the data field set to TRUE.

With the System() call, it is easy to provide programs with specific input, output and error output handles. The tags SYS_Input, SYS_Output and SYS_ErrorOutput (defined in dos/dostags.h) are used to supply the input, output and error output file handles. A program can pass its own input, output and error handles to a synchronously launched program by passing the results of Input(), Output() and ErrorOutput() respectively. Note that with a synchronous System() call, the OS will not close these handles when the spawned process exits. In the case of an asynchronously launched program, the launching program normally must provide new IO handles since the system automatically closes these handles when the asynchronous process ends. Because AmigaDOS wants separate handles for input and output, System() will automatically create an output handle if it's passed a handle for SYS_Input and NULL for SYS_Output. This allows a program to open a CON: window for input and use it for both input and output, as System() will test to see if input is interactive and, if so, will attempt to open "*" for output to that console. If the input file handle is not interactive, System() opens "*" on the current console task.

Programs launched using System() are not restricted to the built-in, or Boot, shell. In the near future, System() will be able to take advantage of specially designed shells (the design requirements of these special shells have not yet been documented). Two tags, SYS_UserShell and SYS_CustomShell, specify which shell System() should use to execute the command-line. By using the SYS_UserShell tag with a tag value of TRUE, an application tells System() to send a command to the user's preferred shell rather that the boot shell (Note that the default user shell is the boot shell). If an application opens a shell for the user or executes the user's command-lines, it should
tell System() to use the user shell. If an application requires consistent shell behavior, it must not use the user shell because the user can change the user shell. Another shell tag, SYS_CustomShell, allows an application to choose other shells besides the boot and user shells. This tag's data field should contain the custom shell's name as it appears in the system resident list.

Although it does offer many features, System() does have some limitations. First, because command paths currently only exist in the CLI structure, Workbench (non-CLI) processes have no paths. Consequently, when a Workbench process calls a program using System(), the shell has no path to search for that program (aside from the system default search path of C: and the current directory). A second limitation of the System() function involves CTRL-C/D/E/F handling. When a task opens a CON: window to provide a handle for a System()-launched command, that task is the owner of the handle. This has two effects. A System()-launched command running in that CON:
window will only be able to receive CTRL-C/D/E/F signals while it is doing input or output to the window (i.e. when it has a pending read or write). If the task that owns the handle is still around, it receives CTRL-C/D/E/F signals whenever those keys are pressed in the CON: window.

== The Con-handler ==

The con-handler (CON:) has many enhancements that allow programs to further customize their console windows. An application requests these new features by appending keywords to the end of the CON: specification string for Open(). These keywords may appear in any order after the title string in the CON: specification.

These new keywords are:

AUTO Don't open CON: window until/unless input or
output occurs
CLOSE Put a close gadget on the CON: window
WAIT Hold off Close until user clicks Close or types CTRL-\
WINDOW 0xaddr Use specified window (may be on a custom screen)
SCREEN name Open on specified public screen

The additional CON: keywords BACKDROP, NODRAG, NOBORDER, NOSIZE, SIMPLE, and SMART, allow control of other attributes of a CON: window.

An AUTO/CLOSE/WAIT CON: window is perfect for C startup code and for asynchronous System() startup of arbitrary commands. Because of the ''auto con'' feature (AUTO), the system will never open the CON: window of a program that doesn't do any stdio (example: Calculator). If a command does stdio input or output, the window will not open until stdio occurs. If the window opens, the wait feature (WAIT) causes the window to stay open until the user types CTRL-\ (end of file) or clicks the Close gadget. The CLOSE keyword tells the con-handler to put a close gadget on the CON: window.

Example: ''CON:/0/0/640/200/My Title/AUTO/CLOSE/WAIT''

The SCREEN keyword along with a public screen name allows an application to open a CON: window on that public screen. Alternately, an application can use the WINDOW keyword to attach a console to an already open Intuition window. The hex address of the Intuition window must follow the WINDOW keyword. This makes it possible for System()-launched programs to do their stdio in a window on a custom screen.

== System() Example ==

The example code, SystemTest.c, provides two simple subroutines for executing external commands, and demonstrates the following features:

* Synchronous System() command execution using the calling program's Input()/Output().
* Synchronous System() command execution in a custom screen window.
* Asynchronous System() command startup with an AUTO/CLOSE/WAIT window.
* OpenScreenTags and OpenWindowTags for a window.

<syntaxhighlight>
/* SystemTest.c
*
* Demonstration of System(), AUTO CON, and custom screen CON
*/

#include <exec/types.h>
#include <exec/libraries.h>
#include <dos/dos.h>
#include <dos/dostags.h>
#include <intuition/intuition.h>
#include <graphics/displayinfo.h>

#include <proto/dos.h>
#include <proto/exec.h>
#include <proto/utility.h>
#include <proto/intuition.h>

/* our function error codes */
#define SYSTEMFAIL (-1L)
#define WINDOWFAIL (-2L)

/* function prototypes */
LONG beginCommand(UBYTE *command);
LONG doCommand(UBYTE *command, BPTR other);
VOID checkResult(UBYTE *command, LONG result);

/* Formatted version string for the VERSION command */
UBYTE *vers = "\0$VER: SystemTest 53.1";

struct Library *IntuitionBase;

int main(int argc, char **argv)
{
extern struct Library *DOSBase;
struct Screen *scr = NULL;
struct Window *win = NULL;
ULONG penspecterm = ~0;
LONG result;
BPTR file;
UBYTE *command;
UBYTE buf[128];

if(!(IntuitionBase = IExec->OpenLibrary("intuition.library", 50)))
{
IDOS->Printf("This example requires intuition.library V50 or higher\n");
return RETURN_FAIL;
}

/* SYNCHRONOUS SYSTEM() WITH OUR INPUT/OUTPUT
*/
IDOS->Printf("\n*** SystemTest: Synchronous System call 'dir libs:':\n");
command = "dir libs:";
result = doCommand(command,NULL);
checkResult(command,result);
IDOS->Printf("\n*** SystemTest: Synchronous System call of nonexistant command:\n");
command = "badcommand";
result = doCommand(command,NULL);
checkResult(command,result);

IDOS->Printf("\n*** SystemTest: Synchronous System call 'ask \"...Answer y now\"':\n");
command =
"ask \"Ready for CON: on a Custom Screen? Answer y now (should return 5):\"";
result = doCommand(command,NULL);
checkResult(command,result);

/* SYNCHRONOUS SYSTEM() WITH CON: IN A CUSTOM SCREEN AND WINDOW
*/
if(scr = IIntuition->OpenScreenTags(NULL,
SA_Width, 640,
SA_Height, 200,
SA_Depth, 3,
SA_DisplayID, HIRES_KEY,
SA_Pens, &penspecterm, /* Give us New Look */
TAG_END))
{
if(win = IIntuition->OpenWindowTags(NULL,
WA_CustomScreen, scr,
WA_Flags, WINDOWDRAG|WINDOWCLOSE|ACTIVATE,
WA_IDCMP, CLOSEWINDOW,
WA_Top, 20,
WA_Height, scr->Height - 20,
WA_Title, "Custom Window",
WA_ScreenTitle, "Custom Screen",
TAG_END))
{
IUtility->SNPrintf(buf, sizeof(buf), "CON://///WINDOW0x%lx", win); /* adds window pointer */
if(file = IDOS->Open(buf, MODE_OLDFILE))
{
command = "echo \"CLI commands on a custom screen!\"";
result = doCommand(command,file);
command = "dir libs:";
result = doCommand(command,file);
command = "echo \"( Click CLOSE gadget, or type CTRL-C )\"";
result = doCommand(command,file);
Wait(1 << win->UserPort->mp_SigBit | SIGBREAKF_CTRL_C);
IDOS->Close(file); /* Closes the window too */
}
else IIntuition->CloseWindow(win);
}
IIntuition->CloseScreen(scr);
}

IDOS->Printf("\n*** SystemTest: Synchronous System call 'ask \"...Answer y now\"':\n");
command = "ask \"Ready for Asynchronous demo? Answer y now (should return 5):\"";
result = doCommand(command,NULL);
checkResult(command,result);

/* ASYNCHRONOUS SYSTEM() WITH ON-DEMAND AUTO/WAIT CON:
*/
IDOS->Printf("\n*** SystemTest: Asynchronous startup of 'Sys:Utilities/Clock':\n");
command = "SYS:Utilities/Clock";
result = beginCommand(command);
checkResult(command,result);

IDOS->Printf("\n*** SystemTest: Asynchronous startup of 'avail':\n");
command = "avail";
result = beginCommand(command);
checkResult(command,result);

IDOS->Printf("\nSystemTest exiting. Close Clock and Autocon window when you wish.\n");

IExec->CloseLibrary(IntuitionBase);
return RETURN_OK;
}

/*
* Synchronous external command (wait for return)
* Uses your Input/Output unless you supply other handle
* Result will be return code of the command, unless the System() call
* itself fails, in which case the result will be -1
*/
LONG doCommand(UBYTE *command, BPTR other)
{
struct TagItem stags[4];

stags[0].ti_Tag = SYS_Input;
stags[0].ti_Data = other ? other : Input();
stags[1].ti_Tag = SYS_Output;
stags[1].ti_Data = other ? NULL: Output();
stags[3].ti_Tag = TAG_END;
return IDOS->System(command, stags);
}

/*
* Asynchronous external command started with its own autocon Input/Output
* This routine shows use of the SYS_UserShell tag as well.
* Result will only reflect whether System() call itself succeeded.
* If System() call fails, result will be -1L
* We are using -2L as result if our Open of CON: fails
*/
UBYTE *autocon="CON:0/40/640/150/Auto CON Window Opens if Needed/auto/close/wait";
LONG beginCommand(UBYTE *command)
{
struct TagItem stags[5];
BPTR file;

if(file = IDOS->Open(autocon, MODE_OLDFILE))
{
stags[0].ti_Tag = SYS_Input;
stags[0].ti_Data = file;
stags[1].ti_Tag = SYS_Output;
stags[1].ti_Data = NULL;
stags[2].ti_Tag = SYS_Asynch;
stags[2].ti_Data = TRUE;
stags[3].ti_Tag = SYS_UserShell;
stags[3].ti_Data = TRUE;
stags[4].ti_Tag = TAG_END;
return IDOS->System(command, stags);
}
else return(WINDOWFAIL);
}

/*
* Demo routine outputs result of System
*/
VOID checkResult(UBYTE *command, LONG result)
{
if(result == SYSTEMFAIL)
IDOS->Printf("*** SystemTest: could not start process for command\n");
else if(result == WINDOWFAIL)
IDOS->Printf("*** SystemTest: can't open con: for command\n");
else
IDOS->Printf("*** SystemTest: command (if synchronous) returned %ld\n",result);
}
</syntaxhighlight>

Programming AmigaOS 4: Transparent Windows

2018-10-06T22:28:08Z

Frédéric Khannouf: Replaced german Word with english equivalent

''This article was adapted from Amiga Future magazine's series on developing for AmigaOS....''

With AmigaOS 4.1 a new technology was introduced, which lets you display (partially) transparent windows thus showing the content behind the window. Additionally, with this technology you can create rounded window corners. We will take a closer look today at the programming characteristics behind these options.

In the first block we will deal with transparent windows, while in the second block we will see how you can create transparent areas within a window or how you can set the window based on the outline of an image.

= Compositing =

In order to be able to use compositing you need AmigaOS in the version 4.1 (so, SysBase->lib_Version >= 53). Moreover, your screen must have a colour depth of at least 16 Bit (so Highcolour or Truecolour). The user can also set in the GUI-Prefs whether transparency is allowed. 'Visual effects for layer' must be activated for it. You can certainly check that in the following way:

<syntaxhighlight>
if(( dri = IIntuition->GetScreenDrawInfo(window->WScreen) ))
{
IIntuition->GetGUIAttrs(NULL,dri,GUIA_SpecialEffects,&specialfx,TAG_END);
}
</syntaxhighlight>

If the variable "specialfx" is set as TRUE, the user has activated the setting and the particular screen has at least 16 Bit colour depth.

= Transparent windows =

To make a window transparent, three new tags are sufficient. They must be passed as/when the window is opened to IIntuition->OpenWindowTags() or rather, IIntuition->NewObject(IWindow->WINDOW_GetClass(),...).

With the tag "WA_Opaqueness" you can determine how opaque or transparent the complete window should be. The possible values margin begins with 0 for completely transparent, which means, you cannot see anything from the contents or the window itself and the underlying screen content is fully displayed. There are also value margins up to 255 for completely opaque display, which corresponds to the standard display. In that case, the complete window content is shown and what is behind is not visible. A mean value of 128 would display one half of the window content and one half of the screen behind it. However, if you want to use this setting, you must additionally set the tag "WA_OverrideOpaqueness" to TRUE. Only then will the global settings from the GUI-Prefs program be ignored and a divergent transparency will be possible for the selected window.

With the third tag "WA_FadeTime" you can set up a delay time, which will be active when you open/close the window as well as when you change the transparent value (WA_Opaqueness). The value is a time span in microseconds (1,000,000 microseconds = 1 second). The standard is 0, which means, no delay. If you enter 1,000,000, it will take one second until the window is completely displayed when opened. Whatever, it's a nice gimmick.

You can also change all three tags retrospectively:

<syntaxhighlight>
Intuition->SetWindowAttrs(window,WA_Opaqueness,opaqueness,TAG_END);
</syntaxhighlight>

On the other hand, you can request the current tag values with

<syntaxhighlight>
IIntuition->GetAttr(WA_Opaqueness,winobj,&opaqueness)
</syntaxhighlight>

The so far covered details are included in the sample program "OpaquenessExample.c", where you can try them out.

<syntaxhighlight>
/* Michael Christoph
* OpaquenessExample.c
*
* gcc OpaquenessExample.c -o OpaquenessExample -l auto
*/

/******************************* INCLUDES *************************************/

#include <intuition/intuition.h>
#include <intuition/gui.h>
#include <intuition/icclass.h>
#include <libraries/gadtools.h>
#include <reaction/reaction.h>
#include <reaction/reaction_macros.h>
#include <classes/window.h>
#include <gadgets/slider.h>
#include <images/label.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>
#include <proto/window.h>
#include <proto/layout.h>
#include <proto/slider.h>
#include <proto/label.h>

/******************************************************************************/

static const char *version USED = "\0$VER: OpaquenessExample 1.0 (06.01.2009) - (c) Jan.2009 by Meicky-Soft\n";

/******************************************************************************/

enum
{
OBJ_SLIDER_1,
OBJ_SLIDER_2,
OBJ_MAX
};

#define OBJ(x) objects[x]
#define GAD(x) (struct Gadget *)objects[x]

/******************************************************************************/

int main()
{
struct RDArgs *rda;
struct Window *window;
struct DrawInfo *dri;
Object *win;
Object *objects[OBJ_MAX];

BOOL canfade = FALSE;
uint32 specialfx = 0;
uint32 fade_time = 50;
uint32 opaqueness = 255;

uint32 sigmask = 0;
uint32 result = 0;
uint16 code = 0;
BOOL done = FALSE;

enum { ARG_pubscreen, ARG_MAX };
ULONG args[ARG_MAX]={ 0 };

/* AmigaOS 4.1 ist erforderlich */
if(SysBase->lib_Version >= 53)
{
/* Aufrufargumente auswerten */
if((rda = IDOS->ReadArgs("PUBSCREEN/K",(LONG*)args,NULL)))
{
win = WindowObject,
WA_Title, "Transparent window",
WA_DragBar, TRUE,
WA_CloseGadget, TRUE,
WA_SizeGadget, TRUE,
WA_DepthGadget, TRUE,
WA_Activate, TRUE,
WA_Width, 400,
WA_OverrideOpaqueness, TRUE, /* Globale Einstellungen ignorieren */
WA_Opaqueness, 255, /* Volldeckend Ëffnen */
WA_FadeTime, 500000, /* VerzËgerungszeit in Mikrosekunden */
(args[ARG_pubscreen] ? WA_PubScreenName : TAG_IGNORE), args[ARG_pubscreen],
WINDOW_Position, WPOS_CENTERSCREEN,
WINDOW_Layout, VLayoutObject,
LAYOUT_SpaceOuter, TRUE,

LAYOUT_AddChild, OBJ(OBJ_SLIDER_1) = SliderObject,
GA_ID, OBJ_SLIDER_1,
GA_RelVerify, TRUE,
SLIDER_Min, 10,
SLIDER_Max, 100,
SLIDER_Level, 50,
SLIDER_KnobDelta, 10,
SLIDER_Orientation, SLIDER_HORIZONTAL,
SLIDER_Ticks, 11,
SLIDER_ShortTicks, TRUE,
SLIDER_LevelFormat, "%3ld",
SLIDER_LevelPlace, PLACETEXT_IN,
SLIDER_LevelMaxLen, 3,
End,
Label(" Fade Time (1/100s) "),
CHILD_WeightedHeight, 0,

LAYOUT_AddChild, OBJ(OBJ_SLIDER_2) = SliderObject,
GA_ID, OBJ_SLIDER_2,
GA_RelVerify, TRUE,
SLIDER_Min, 20,
SLIDER_Max, 255,
SLIDER_Level, 255,
SLIDER_KnobDelta, 10,
SLIDER_Orientation, SLIDER_HORIZONTAL,
SLIDER_Ticks, 21,
SLIDER_ShortTicks, TRUE,
SLIDER_LevelFormat, "%3ld",
SLIDER_LevelPlace, PLACETEXT_IN,
SLIDER_LevelMaxLen, 3,
TAG_END),
Label(" Opaqueness "),
CHILD_WeightedHeight, 0,

TAG_END),
TAG_END);

if((window = RA_OpenWindow(win)))
{
IIntuition->GetAttr(WINDOW_SigMask, win, &sigmask);

/* ist Composing aktiviert und mËglich ? */
if((dri = IIntuition->GetScreenDrawInfo(window->WScreen)))
{
IIntuition->GetGUIAttrs(NULL,dri,GUIA_SpecialEffects,&specialfx,TAG_END);
canfade = (BOOL)specialfx;

if(!canfade)
{
/* deaktiviert: dann auch Gadgets sperren, da ohne Effekt */
IIntuition->SetGadgetAttrs(GAD(OBJ_SLIDER_1),window,NULL,
GA_Disabled,TRUE,TAG_END);
IIntuition->SetGadgetAttrs(GAD(OBJ_SLIDER_2),window,NULL,
GA_Disabled,TRUE,TAG_END);
}
}

while(!done)
{
if(IExec->Wait(sigmask | SIGBREAKF_CTRL_C) & SIGBREAKF_CTRL_C)
{
done = TRUE;
}

while((result = RA_HandleInput(win,&code)))
{
switch(result & WMHI_CLASSMASK)
{
case WMHI_CLOSEWINDOW:
done = TRUE;
break;

case WMHI_GADGETUP:
switch(result & WMHI_GADGETMASK)
{
case OBJ_SLIDER_1:
if (canfade)
{
IIntuition->GetAttrs(GAD(OBJ_SLIDER_1), SLIDER_Level, &fade_time, TAG_END);
IIntuition->SetWindowAttrs(window, WA_FadeTime, fade_time * 10000, TAG_END);
}
break;

case OBJ_SLIDER_2:
if (canfade)
{
IIntuition->GetAttrs(GAD(OBJ_SLIDER_2), SLIDER_Level, &opaqueness, TAG_END);
IIntuition->SetWindowAttrs(window, WA_Opaqueness, opaqueness, TAG_END);

/* SetWindowAttr() kehrt sofort zurÂ¸ck, daher warten wir kurz */
/* bis das Fenster das Fading abgeschlossen hat, bevor die nâ°chste */
/* Verâ°nderung vorgenommen wird. */
IDOS->Delay(fade_time/2);
}
break;
}
break;
}
}
}
}

IIntuition->DisposeObject(win);

IDOS->FreeArgs(rda);
}
else IDOS->PrintFault(IDOS->IoErr(),"OpaquenessExample");
}
else IDOS->Printf("program required AmigaOS 4.1\n");

return 0;
}
</syntaxhighlight>

[[File:AF108_opaqueness_grab.png|frame|center]]

= Non-square windows =

The so far mentioned information always relates to complete square windows. In this second block we will see how you can 'remove' parts of a window or see through a hole in the window. These options are more complex, but AmigaOS supports programmers with its new functions. Since the Autodocs in this field are still quite incomplete we tried to compile all the important information.

= Loading graphics =

First of all, we need a graphic that will set the form of the window. The intuition.library supports us here with matching new functions that we haven't had a chance to present you yet. The image data is loaded in the memory with IIntuition->ObtainBitMapSource().The tag BMS_DoShade is important here in order to create/provide the alpha-channel data as well. At the moment this is only possible with PNG graphics. Other graphic formats do not provide this information.

IIntuition->ObtainBitMapInstance() declares a pointer to the image management. To get the actual image data you must request the desired values with IIntuition->BitMapInstanceControl(). Some important tags are here BMICTRL_GetWidth and BMICTRL_GetHeight for the size as well as BMICTRL_GetBitMap and BMICTRL_GetAlphaMap for the image data, i.e., the alpha mask. There is IIntuition->ReleaseBitMapInstance() and Iintuition->ReleaseBitMapSource() for release. The functions that you will need are compiled in the following list. The image data can be drawn with the usual functions such as IGraphics->BltBitMapTags().

<syntaxhighlight>
struct Screen *scr;
APTR source;
APTR instance;
struct BitMap *bitmap;
struct BitMap *alpha;
ULONG width;
ULONG height;

/* load the graphic in the memory, if necessary (intern via Datatype) */
if((source = IIntuition->ObtainBitMapSource((STRPTR)args[ARG_filename],BMS_DoShade,TRUE,TAG_END)))
{
/* request a bitmap instance for the screen */
if((instance = IIntuition->ObtainBitMapInstance(source,scr,TAG_END)))
{
/* Request image information and bitmap*/
IIntuition->BitMapInstanceControl(instance,
BMICTRL_GetBitMap, &bitmap,
BMICTRL_GetAlphaMap, &alpha,
BMICTRL_GetWidth, &width,
BMICTRL_GetHeight, &height,
TAG_DONE );

if(bitmap && alpha)
{
/* Image data can be processed /blitted now */
}
else IDOS->Printf("cannot get (alpha) bitmaps\n");

/* r BitMap Instance */
IIntuition->ReleaseBitMapInstance(instance);
}
else IDOS->Printf("cannot get instance of picture\n");

/* release graphic file */
IIntuition->ReleaseBitMapSource(source);
}
else IDOS->Printf("loading picture file failed\n");
</syntaxhighlight>

= Define window areas =

The existing clipping system has been expanded in order to be able to set the areas in a window that display contents, that is, that let the background show through. With ILayers->InstallClipRegion() you could set even earlier rectangular areas in a window, in which a blit operation can draw data. This way, you can, for example, protect separate areas of a window too, if graphic data is larger than the window. However, in order to apply the ClipRect structure to an alpha channel you must use a private function of the layers. library:

<syntaxhighlight>
ILayers->AllocClipRect()
</syntaxhighlight>

This is provided exclusively for this task. The counterpart to it is ILayers->FreeClipRect(), that releases again the structure. The structure is already pre-initialised, so that only a few fields must be adjusted to your needs. On the one hand, you must store the graphic size in "bounds" and enter it in "BitMap". The required memory area for it can be created with IGraphics->AllocBitMap(). Then you must also blit the alpha-channel bitmap with IGraphics->BltBitMapTags(). The only thing you need to keep in mind in this whole procedure is that you automatically de-allocate the entered BitMap when you allocate the ClipRect structure! In case you do not want to do it, you must first set the field on NULL and de-allocate the BitMap with IGraphics->FreeBitMap(). These are the matching code rows for this part of the workshop:

<syntaxhighlight>
struct ClipRect *ac;

/* allocate and initialise ClipRect structure */
if((ac = ILayers->AllocClipRect(&(scr->LayerInfo))))
{
struct TagItem bmtags[3] = { { BMATags_RGBFormat, RGBFB_ALPHA8 },
{ BMATags_Friend, (ULONG)scr->RastPort.BitMap },
{ TAG_END, 0 } };

/* alllocate Alpha-ClipRect and request memory for Bitmap */
ac->bounds.MinX = 0;
ac->bounds.MinY = 0;
ac->bounds.MaxX = width-1,
ac->bounds.MaxY = height-1;
ac->Next = NULL;
if((ac->BitMap = IGraphics->AllocBitMap(width,height,8,BMF_DISPLAYABLE|BMF_CLEAR|BMF_CHECKVALUE,(struct BitMap *)bmtags)))
{
/* Fill Alpha-ClipRect with Alpha-Bitmap */
IGraphics->BltBitMapTags(BLITA_Source, alpha,
BLITA_SrcType, BLITT_CHUNKY,
BLITA_SrcBytesPerRow, width,
BLITA_Dest, ac->BitMap,
BLITA_Width, width,
BLITA_Height, height,
TAG_DONE );

/* ... */
}
else IDOS->Printf("cannot allocate alpha mask\n");

/* ClipRect deallocate; it also deallocates ac->BitMap! */
ILayers->FreeClipRect(&(scr->LayerInfo),ac);
}
else IDOS->Printf("cannot allocate cliprect\n");
</syntaxhighlight>

= Window show yourself =

What is left is opening the window and blitting the graphic bitmap with IGraphics->BltBitMapRastPort(). You will need for it the following code rows:

<syntaxhighlight>
struct Window *win;

/* Open window with the Alpha mask */
if((win = IIntuition->OpenWindowTags(NULL,
WA_Width, width,
WA_Height, height,
WA_Borderless, TRUE,
WA_AlphaClips, ac,
...
TAG_DONE)))
{
/* blit the graphic file into the window */
IGraphics->BltBitMapRastPort(bitmap, 0, 0, win->RPort, 0, 0, width, height, MINTERM_ABC|MINTERM_ABNC);
}
</syntaxhighlight>

When you open the window, you must also enter the tag WA_AlphaClips. The window will be opened without a frame and without system symbols. They are not shown, but as soon as you activate the window, the frame elements are drawn with Intuition, at least as far as the alpha mask allows it. You can also target the alpha mask display. Just do not copy any image data into the Rastport after you have opened the window. The alpha mask does not only set the opaque and transparent points, but it can also be created gradually. Thus, even image parts can appear as half-transparent and let the background shine through. The 'partly transparent ball' graphic shows the result.

You should also keep in mind that the window may not be of the GimmeZeroZero type. In this case there are already internal clipping masks, which cannot be combined with the alpha-clipping.

The program "BorderlessWindow" serves as a complete example for this topic showing all the mentioned functions in a practical interplay. A matching graphic is also included. Have fun experimenting with the source-code and looking for new possibilities!

<syntaxhighlight>
/* Michael Christoph
* BorderlessWindow.c
*
* gcc BorderlessWindow.c -o BorderlessWindow -l auto
*/

/******************************* INCLUDES *************************************/

#include <exec/libraries.h>
#include <graphics/blitattr.h>
#include <graphics/composite.h>
#include <intuition/intuition.h>
#include <intuition/bitmapshare.h>
#include <intuition/gui.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/graphics.h>
#include <proto/intuition.h>
#include <proto/layers.h>

/******************************************************************************/

static const char *version USED = "\0$VER: BorderlessWindow 1.1 (22.07.2013) - (c) Jan.2009 by Meicky-Soft\n";

/******************************************************************************/

int main(int argc, char *argv[])
{
int res = RETURN_FAIL;

struct RDArgs *rda;
struct Screen *scr;
struct Window *win;
struct ClipRect *ac;
struct DrawInfo *dri;
struct BitMap *bitmap;
struct BitMap *alpha;
APTR source;
APTR instance;
ULONG width;
ULONG height;
ULONG specialfx;

enum { ARG_filename, ARG_pubscreen, ARG_MAX };
ULONG args[ARG_MAX]={ (ULONG)"testpic.png",0 };

/* AmigaOS 4.1 ist erforderlich */
if(SysBase->lib_Version >= 53)
{
/* Aufrufargumente auswerten */
if((rda = IDOS->ReadArgs("FILENAME,PUBSCREEN/K",(LONG*)args,NULL)))
{
/* Bildschirm auf dem die Anzeige erfolgt festlegen */
if((scr = IIntuition->LockPubScreen((STRPTR)args[ARG_pubscreen])))
{
/* sicherstellen dass der Bildschirm Alpha Composing unterstÂ¸tzt */
if(( dri = IIntuition->GetScreenDrawInfo(scr)))
{
IIntuition->GetGUIAttrs(NULL,dri,GUIA_SpecialEffects,&specialfx,TAG_END);
if(!specialfx) IDOS->Printf("WARNING: screen do not support alpha composing\n");

IIntuition->FreeScreenDrawInfo(scr,dri);
}

/* die Grafik bei Bedarf in den Speicher laden (intern via Datatype) */
if((source = IIntuition->ObtainBitMapSource((STRPTR)args[ARG_filename],
BMS_DoShade, TRUE,
BMS_DoMask, TRUE,
TAG_END)))
{
/* eine Bitmap-Instance fÂ¸r den eigenen Bildschirm anfordern */
if((instance = IIntuition->ObtainBitMapInstance(source,scr,TAG_END)))
{
/* Bildinformationen und Biptmap erfragen */
IIntuition->BitMapInstanceControl(instance,
BMICTRL_GetBitMap, &bitmap,
BMICTRL_GetAlphaMap, &alpha,
BMICTRL_GetWidth, &width,
BMICTRL_GetHeight, &height,
TAG_END );
if(bitmap && alpha)
{
/* ClipRect Struktur anlegen und initialisieren */
if((ac = ILayers->AllocClipRect(&(scr->LayerInfo))))
{
/* Alpha-ClipRect belegen und Speicher fÂ¸r Bitmap anfordern */
ac->bounds.MinX = 0;
ac->bounds.MinY = 0;
ac->bounds.MaxX = width-1,
ac->bounds.MaxY = height-1;
ac->Next = NULL;
if((ac->BitMap = IGraphics->AllocBitMapTags(width, height, 8,
BMATags_Displayable, TRUE,
BMATags_Clear, TRUE,
BMATags_PixelFormat, PIXF_ALPHA8,
BMATags_Friend, scr->RastPort.BitMap,
TAG_END)))
{
/* Alpha-ClipRect mit der Alpha-Bitmap fÂ¸llen */
IGraphics->BltBitMapTags(BLITA_Source, alpha,
BLITA_SrcType, BLITT_CHUNKY,
BLITA_SrcBytesPerRow, width,
BLITA_Dest, ac->BitMap,
BLITA_Width, width,
BLITA_Height, height,
TAG_END );

/* Rahmenloses Fenster Ëffnen */
if((win = IIntuition->OpenWindowTags(NULL,
WA_Left, 1580,
WA_Top, 120,
WA_Width, width,
WA_Height, height,
WA_CloseGadget, FALSE,
WA_DragBar, FALSE,
WA_DepthGadget, FALSE,
WA_SizeGadget, FALSE,
WA_Borderless, TRUE,
WA_ToolBox, TRUE,
WA_AlphaClips, ac,
WA_CustomScreen,scr,
WA_Title, "Borderless window",
WA_IDCMP, IDCMP_MOUSEBUTTONS,
TAG_END )))
{
/* das komplette Fenster als dragable definieren */
struct Gadget draggad = { NULL, 0,0, width,height,
GFLG_GADGHNONE, 0, GTYP_WDRAGGING,
NULL,NULL,NULL,0,0,0,NULL };
win->FirstGadget = &draggad;

/* die Grafikdatei in das Fenster blitten */
IGraphics->BltBitMapRastPort(bitmap, 0, 0, win->RPort,
0, 0, width, height, MINTERM_ABC | MINTERM_ABNC);

/* warten auf CTRL-C zum Programm beenden */
IExec->Wait(SIGBREAKF_CTRL_C);

res = RETURN_OK;

/* Fenster schlieï¬en */
IIntuition->CloseWindow(win);
}
else IDOS->Printf("can not open window\n");
}
else IDOS->Printf("can not allocate alpha mask\n");

/* ClipRect freigeben; gibt auch ac->BitMap frei ! */
ILayers->FreeClipRect(&(scr->LayerInfo),ac);
}
else IDOS->Printf("can not allocate cliprect\n");
}
else IDOS->Printf("can not get (alpha) bitmaps\n");

/* BitMap Instance freigeben */
IIntuition->ReleaseBitMapInstance(instance);
}
else IDOS->Printf("can not get instance of picture\n");

/* Grafikdatei freigeben */
IIntuition->ReleaseBitMapSource(source);
}
else IDOS->Printf("loading picture file failed\n");

/* Bildschirm freigeben */
IIntuition->UnlockPubScreen(NULL,scr);
}
else IDOS->Printf("can not lock pubscreen\n");

IDOS->FreeArgs(rda);
}
else { IDOS->PrintFault(IDOS->IoErr(),"BorderlessWindow"); res = RETURN_ERROR; }
}
else IDOS->Printf("Program requires AmigaOS 4.1\n");

return res;
}
</syntaxhighlight>

Grab the test graphic here: [[Media:testpic.png|testpic.png]].

[[File:AF108_borderless_grab.png|frame|center]]

= Outlook =

You can look forward to the next issue, in which we will deal with datatypes. Do not expect any novelties regarding the program, but for the sake of completeness we should mention these options as well.

[[File:AF108_FensterLoch_grab.png|frame|center]]
With a hole in a window you can create funny effects, especially if you move the window around.

= Authors =

Written by Michael Christoph and Aleksandra Schmidt-Pendarovska 
Copyright (c) 2013 Michael Christoph

Programming AmigaOS 4: Transparent Windows

2018-10-04T21:30:48Z

Frédéric Khannouf: Corrected small typo

''This article was adapted from Amiga Future magazine's series on developing for AmigaOS....''

With AmigaOS 4.1 a new technology was introduced, which lets you display (partially) transparent windows thus showing the content behind the window. Additionally, with this technology you can create rounded window corners. We will take a closer look today at the programming characteristics behind these options.

In the first block we will deal with transparent windows, while in the second block we will see how you can create transparent areas within a window or how you can set the window based on the outline of an image.

= Compositing =

In order to be able to use compositing you need AmigaOS in the version 4.1 (so, SysBase->lib_Version >= 53). Moreover, your screen must have a colour depth of at least 16 Bit (so Highcolour or Truecolour). The user can also set in the GUI-Prefs whether transparency is allowed. 'Visual effects for layer' must be activated for it. You can certainly check that in the following way:

<syntaxhighlight>
if(( dri = IIntuition->GetScreenDrawInfo(window->WScreen) ))
{
IIntuition->GetGUIAttrs(NULL,dri,GUIA_SpecialEffects,&specialfx,TAG_END);
}
</syntaxhighlight>

If the variable "specialfx" is set as TRUE, the user has activated the setting and the particular screen has at least 16 Bit colour depth.

= Transparent windows =

To make a window transparent, three new tags are sufficient. They must be passed as/when the window is opened to IIntuition->OpenWindowTags() bzw. IIntuition->NewObject(IWindow->WINDOW_GetClass(),...).

With the tag "WA_Opaqueness" you can determine how opaque or transparent the complete window should be. The possible values margin begins with 0 for completely transparent, which means, you cannot see anything from the contents or the window itself and the underlying screen content is fully displayed. There are also value margins up to 255 for completely opaque display, which corresponds to the standard display. In that case, the complete window content is shown and what is behind is not visible. A mean value of 128 would display one half of the window content and one half of the screen behind it. However, if you want to use this setting, you must additionally set the tag "WA_OverrideOpaqueness" to TRUE. Only then will the global settings from the GUI-Prefs program be ignored and a divergent transparency will be possible for the selected window.

With the third tag "WA_FadeTime" you can set up a delay time, which will be active when you open/close the window as well as when you change the transparent value (WA_Opaqueness). The value is a time span in microseconds (1,000,000 microseconds = 1 second). The standard is 0, which means, no delay. If you enter 1,000,000, it will take one second until the window is completely displayed when opened. Whatever, it's a nice gimmick.

You can also change all three tags retrospectively:

<syntaxhighlight>
Intuition->SetWindowAttrs(window,WA_Opaqueness,opaqueness,TAG_END);
</syntaxhighlight>

On the other hand, you can request the current tag values with

<syntaxhighlight>
IIntuition->GetAttr(WA_Opaqueness,winobj,&opaqueness)
</syntaxhighlight>

The so far covered details are included in the sample program "OpaquenessExample.c", where you can try them out.

<syntaxhighlight>
/* Michael Christoph
* OpaquenessExample.c
*
* gcc OpaquenessExample.c -o OpaquenessExample -l auto
*/

/******************************* INCLUDES *************************************/

#include <intuition/intuition.h>
#include <intuition/gui.h>
#include <intuition/icclass.h>
#include <libraries/gadtools.h>
#include <reaction/reaction.h>
#include <reaction/reaction_macros.h>
#include <classes/window.h>
#include <gadgets/slider.h>
#include <images/label.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>
#include <proto/window.h>
#include <proto/layout.h>
#include <proto/slider.h>
#include <proto/label.h>

/******************************************************************************/

static const char *version USED = "\0$VER: OpaquenessExample 1.0 (06.01.2009) - (c) Jan.2009 by Meicky-Soft\n";

/******************************************************************************/

enum
{
OBJ_SLIDER_1,
OBJ_SLIDER_2,
OBJ_MAX
};

#define OBJ(x) objects[x]
#define GAD(x) (struct Gadget *)objects[x]

/******************************************************************************/

int main()
{
struct RDArgs *rda;
struct Window *window;
struct DrawInfo *dri;
Object *win;
Object *objects[OBJ_MAX];

BOOL canfade = FALSE;
uint32 specialfx = 0;
uint32 fade_time = 50;
uint32 opaqueness = 255;

uint32 sigmask = 0;
uint32 result = 0;
uint16 code = 0;
BOOL done = FALSE;

enum { ARG_pubscreen, ARG_MAX };
ULONG args[ARG_MAX]={ 0 };

/* AmigaOS 4.1 ist erforderlich */
if(SysBase->lib_Version >= 53)
{
/* Aufrufargumente auswerten */
if((rda = IDOS->ReadArgs("PUBSCREEN/K",(LONG*)args,NULL)))
{
win = WindowObject,
WA_Title, "Transparent window",
WA_DragBar, TRUE,
WA_CloseGadget, TRUE,
WA_SizeGadget, TRUE,
WA_DepthGadget, TRUE,
WA_Activate, TRUE,
WA_Width, 400,
WA_OverrideOpaqueness, TRUE, /* Globale Einstellungen ignorieren */
WA_Opaqueness, 255, /* Volldeckend Ëffnen */
WA_FadeTime, 500000, /* VerzËgerungszeit in Mikrosekunden */
(args[ARG_pubscreen] ? WA_PubScreenName : TAG_IGNORE), args[ARG_pubscreen],
WINDOW_Position, WPOS_CENTERSCREEN,
WINDOW_Layout, VLayoutObject,
LAYOUT_SpaceOuter, TRUE,

LAYOUT_AddChild, OBJ(OBJ_SLIDER_1) = SliderObject,
GA_ID, OBJ_SLIDER_1,
GA_RelVerify, TRUE,
SLIDER_Min, 10,
SLIDER_Max, 100,
SLIDER_Level, 50,
SLIDER_KnobDelta, 10,
SLIDER_Orientation, SLIDER_HORIZONTAL,
SLIDER_Ticks, 11,
SLIDER_ShortTicks, TRUE,
SLIDER_LevelFormat, "%3ld",
SLIDER_LevelPlace, PLACETEXT_IN,
SLIDER_LevelMaxLen, 3,
End,
Label(" Fade Time (1/100s) "),
CHILD_WeightedHeight, 0,

LAYOUT_AddChild, OBJ(OBJ_SLIDER_2) = SliderObject,
GA_ID, OBJ_SLIDER_2,
GA_RelVerify, TRUE,
SLIDER_Min, 20,
SLIDER_Max, 255,
SLIDER_Level, 255,
SLIDER_KnobDelta, 10,
SLIDER_Orientation, SLIDER_HORIZONTAL,
SLIDER_Ticks, 21,
SLIDER_ShortTicks, TRUE,
SLIDER_LevelFormat, "%3ld",
SLIDER_LevelPlace, PLACETEXT_IN,
SLIDER_LevelMaxLen, 3,
TAG_END),
Label(" Opaqueness "),
CHILD_WeightedHeight, 0,

TAG_END),
TAG_END);

if((window = RA_OpenWindow(win)))
{
IIntuition->GetAttr(WINDOW_SigMask, win, &sigmask);

/* ist Composing aktiviert und mËglich ? */
if((dri = IIntuition->GetScreenDrawInfo(window->WScreen)))
{
IIntuition->GetGUIAttrs(NULL,dri,GUIA_SpecialEffects,&specialfx,TAG_END);
canfade = (BOOL)specialfx;

if(!canfade)
{
/* deaktiviert: dann auch Gadgets sperren, da ohne Effekt */
IIntuition->SetGadgetAttrs(GAD(OBJ_SLIDER_1),window,NULL,
GA_Disabled,TRUE,TAG_END);
IIntuition->SetGadgetAttrs(GAD(OBJ_SLIDER_2),window,NULL,
GA_Disabled,TRUE,TAG_END);
}
}

while(!done)
{
if(IExec->Wait(sigmask | SIGBREAKF_CTRL_C) & SIGBREAKF_CTRL_C)
{
done = TRUE;
}

while((result = RA_HandleInput(win,&code)))
{
switch(result & WMHI_CLASSMASK)
{
case WMHI_CLOSEWINDOW:
done = TRUE;
break;

case WMHI_GADGETUP:
switch(result & WMHI_GADGETMASK)
{
case OBJ_SLIDER_1:
if (canfade)
{
IIntuition->GetAttrs(GAD(OBJ_SLIDER_1), SLIDER_Level, &fade_time, TAG_END);
IIntuition->SetWindowAttrs(window, WA_FadeTime, fade_time * 10000, TAG_END);
}
break;

case OBJ_SLIDER_2:
if (canfade)
{
IIntuition->GetAttrs(GAD(OBJ_SLIDER_2), SLIDER_Level, &opaqueness, TAG_END);
IIntuition->SetWindowAttrs(window, WA_Opaqueness, opaqueness, TAG_END);

/* SetWindowAttr() kehrt sofort zurÂ¸ck, daher warten wir kurz */
/* bis das Fenster das Fading abgeschlossen hat, bevor die nâ°chste */
/* Verâ°nderung vorgenommen wird. */
IDOS->Delay(fade_time/2);
}
break;
}
break;
}
}
}
}

IIntuition->DisposeObject(win);

IDOS->FreeArgs(rda);
}
else IDOS->PrintFault(IDOS->IoErr(),"OpaquenessExample");
}
else IDOS->Printf("program required AmigaOS 4.1\n");

return 0;
}
</syntaxhighlight>

[[File:AF108_opaqueness_grab.png|frame|center]]

= Non-square windows =

The so far mentioned information always relates to complete square windows. In this second block we will see how you can 'remove' parts of a window or see through a hole in the window. These options are more complex, but AmigaOS supports programmers with its new functions. Since the Autodocs in this field are still quite incomplete we tried to compile all the important information.

= Loading graphics =

First of all, we need a graphic that will set the form of the window. The intuition.library supports us here with matching new functions that we haven't had a chance to present you yet. The image data is loaded in the memory with IIntuition->ObtainBitMapSource().The tag BMS_DoShade is important here in order to create/provide the alpha-channel data as well. At the moment this is only possible with PNG graphics. Other graphic formats do not provide this information.

IIntuition->ObtainBitMapInstance() declares a pointer to the image management. To get the actual image data you must request the desired values with IIntuition->BitMapInstanceControl(). Some important tags are here BMICTRL_GetWidth and BMICTRL_GetHeight for the size as well as BMICTRL_GetBitMap and BMICTRL_GetAlphaMap for the image data, i.e., the alpha mask. There is IIntuition->ReleaseBitMapInstance() and Iintuition->ReleaseBitMapSource() for release. The functions that you will need are compiled in the following list. The image data can be drawn with the usual functions such as IGraphics->BltBitMapTags().

<syntaxhighlight>
struct Screen *scr;
APTR source;
APTR instance;
struct BitMap *bitmap;
struct BitMap *alpha;
ULONG width;
ULONG height;

/* load the graphic in the memory, if necessary (intern via Datatype) */
if((source = IIntuition->ObtainBitMapSource((STRPTR)args[ARG_filename],BMS_DoShade,TRUE,TAG_END)))
{
/* request a bitmap instance for the screen */
if((instance = IIntuition->ObtainBitMapInstance(source,scr,TAG_END)))
{
/* Request image information and bitmap*/
IIntuition->BitMapInstanceControl(instance,
BMICTRL_GetBitMap, &bitmap,
BMICTRL_GetAlphaMap, &alpha,
BMICTRL_GetWidth, &width,
BMICTRL_GetHeight, &height,
TAG_DONE );

if(bitmap && alpha)
{
/* Image data can be processed /blitted now */
}
else IDOS->Printf("cannot get (alpha) bitmaps\n");

/* r BitMap Instance */
IIntuition->ReleaseBitMapInstance(instance);
}
else IDOS->Printf("cannot get instance of picture\n");

/* release graphic file */
IIntuition->ReleaseBitMapSource(source);
}
else IDOS->Printf("loading picture file failed\n");
</syntaxhighlight>

= Define window areas =

The existing clipping system has been expanded in order to be able to set the areas in a window that display contents, that is, that let the background show through. With ILayers->InstallClipRegion() you could set even earlier rectangular areas in a window, in which a blit operation can draw data. This way, you can, for example, protect separate areas of a window too, if graphic data is larger than the window. However, in order to apply the ClipRect structure to an alpha channel you must use a private function of the layers. library:

<syntaxhighlight>
ILayers->AllocClipRect()
</syntaxhighlight>

This is provided exclusively for this task. The counterpart to it is ILayers->FreeClipRect(), that releases again the structure. The structure is already pre-initialised, so that only a few fields must be adjusted to your needs. On the one hand, you must store the graphic size in "bounds" and enter it in "BitMap". The required memory area for it can be created with IGraphics->AllocBitMap(). Then you must also blit the alpha-channel bitmap with IGraphics->BltBitMapTags(). The only thing you need to keep in mind in this whole procedure is that you automatically de-allocate the entered BitMap when you allocate the ClipRect structure! In case you do not want to do it, you must first set the field on NULL and de-allocate the BitMap with IGraphics->FreeBitMap(). These are the matching code rows for this part of the workshop:

<syntaxhighlight>
struct ClipRect *ac;

/* allocate and initialise ClipRect structure */
if((ac = ILayers->AllocClipRect(&(scr->LayerInfo))))
{
struct TagItem bmtags[3] = { { BMATags_RGBFormat, RGBFB_ALPHA8 },
{ BMATags_Friend, (ULONG)scr->RastPort.BitMap },
{ TAG_END, 0 } };

/* alllocate Alpha-ClipRect and request memory for Bitmap */
ac->bounds.MinX = 0;
ac->bounds.MinY = 0;
ac->bounds.MaxX = width-1,
ac->bounds.MaxY = height-1;
ac->Next = NULL;
if((ac->BitMap = IGraphics->AllocBitMap(width,height,8,BMF_DISPLAYABLE|BMF_CLEAR|BMF_CHECKVALUE,(struct BitMap *)bmtags)))
{
/* Fill Alpha-ClipRect with Alpha-Bitmap */
IGraphics->BltBitMapTags(BLITA_Source, alpha,
BLITA_SrcType, BLITT_CHUNKY,
BLITA_SrcBytesPerRow, width,
BLITA_Dest, ac->BitMap,
BLITA_Width, width,
BLITA_Height, height,
TAG_DONE );

/* ... */
}
else IDOS->Printf("cannot allocate alpha mask\n");

/* ClipRect deallocate; it also deallocates ac->BitMap! */
ILayers->FreeClipRect(&(scr->LayerInfo),ac);
}
else IDOS->Printf("cannot allocate cliprect\n");
</syntaxhighlight>

= Window show yourself =

What is left is opening the window and blitting the graphic bitmap with IGraphics->BltBitMapRastPort(). You will need for it the following code rows:

<syntaxhighlight>
struct Window *win;

/* Open window with the Alpha mask */
if((win = IIntuition->OpenWindowTags(NULL,
WA_Width, width,
WA_Height, height,
WA_Borderless, TRUE,
WA_AlphaClips, ac,
...
TAG_DONE)))
{
/* blit the graphic file into the window */
IGraphics->BltBitMapRastPort(bitmap, 0, 0, win->RPort, 0, 0, width, height, MINTERM_ABC|MINTERM_ABNC);
}
</syntaxhighlight>

When you open the window, you must also enter the tag WA_AlphaClips. The window will be opened without a frame and without system symbols. They are not shown, but as soon as you activate the window, the frame elements are drawn with Intuition, at least as far as the alpha mask allows it. You can also target the alpha mask display. Just do not copy any image data into the Rastport after you have opened the window. The alpha mask does not only set the opaque and transparent points, but it can also be created gradually. Thus, even image parts can appear as half-transparent and let the background shine through. The 'partly transparent ball' graphic shows the result.

You should also keep in mind that the window may not be of the GimmeZeroZero type. In this case there are already internal clipping masks, which cannot be combined with the alpha-clipping.

The program "BorderlessWindow" serves as a complete example for this topic showing all the mentioned functions in a practical interplay. A matching graphic is also included. Have fun experimenting with the source-code and looking for new possibilities!

<syntaxhighlight>
/* Michael Christoph
* BorderlessWindow.c
*
* gcc BorderlessWindow.c -o BorderlessWindow -l auto
*/

/******************************* INCLUDES *************************************/

#include <exec/libraries.h>
#include <graphics/blitattr.h>
#include <graphics/composite.h>
#include <intuition/intuition.h>
#include <intuition/bitmapshare.h>
#include <intuition/gui.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/graphics.h>
#include <proto/intuition.h>
#include <proto/layers.h>

/******************************************************************************/

static const char *version USED = "\0$VER: BorderlessWindow 1.1 (22.07.2013) - (c) Jan.2009 by Meicky-Soft\n";

/******************************************************************************/

int main(int argc, char *argv[])
{
int res = RETURN_FAIL;

struct RDArgs *rda;
struct Screen *scr;
struct Window *win;
struct ClipRect *ac;
struct DrawInfo *dri;
struct BitMap *bitmap;
struct BitMap *alpha;
APTR source;
APTR instance;
ULONG width;
ULONG height;
ULONG specialfx;

enum { ARG_filename, ARG_pubscreen, ARG_MAX };
ULONG args[ARG_MAX]={ (ULONG)"testpic.png",0 };

/* AmigaOS 4.1 ist erforderlich */
if(SysBase->lib_Version >= 53)
{
/* Aufrufargumente auswerten */
if((rda = IDOS->ReadArgs("FILENAME,PUBSCREEN/K",(LONG*)args,NULL)))
{
/* Bildschirm auf dem die Anzeige erfolgt festlegen */
if((scr = IIntuition->LockPubScreen((STRPTR)args[ARG_pubscreen])))
{
/* sicherstellen dass der Bildschirm Alpha Composing unterstÂ¸tzt */
if(( dri = IIntuition->GetScreenDrawInfo(scr)))
{
IIntuition->GetGUIAttrs(NULL,dri,GUIA_SpecialEffects,&specialfx,TAG_END);
if(!specialfx) IDOS->Printf("WARNING: screen do not support alpha composing\n");

IIntuition->FreeScreenDrawInfo(scr,dri);
}

/* die Grafik bei Bedarf in den Speicher laden (intern via Datatype) */
if((source = IIntuition->ObtainBitMapSource((STRPTR)args[ARG_filename],
BMS_DoShade, TRUE,
BMS_DoMask, TRUE,
TAG_END)))
{
/* eine Bitmap-Instance fÂ¸r den eigenen Bildschirm anfordern */
if((instance = IIntuition->ObtainBitMapInstance(source,scr,TAG_END)))
{
/* Bildinformationen und Biptmap erfragen */
IIntuition->BitMapInstanceControl(instance,
BMICTRL_GetBitMap, &bitmap,
BMICTRL_GetAlphaMap, &alpha,
BMICTRL_GetWidth, &width,
BMICTRL_GetHeight, &height,
TAG_END );
if(bitmap && alpha)
{
/* ClipRect Struktur anlegen und initialisieren */
if((ac = ILayers->AllocClipRect(&(scr->LayerInfo))))
{
/* Alpha-ClipRect belegen und Speicher fÂ¸r Bitmap anfordern */
ac->bounds.MinX = 0;
ac->bounds.MinY = 0;
ac->bounds.MaxX = width-1,
ac->bounds.MaxY = height-1;
ac->Next = NULL;
if((ac->BitMap = IGraphics->AllocBitMapTags(width, height, 8,
BMATags_Displayable, TRUE,
BMATags_Clear, TRUE,
BMATags_PixelFormat, PIXF_ALPHA8,
BMATags_Friend, scr->RastPort.BitMap,
TAG_END)))
{
/* Alpha-ClipRect mit der Alpha-Bitmap fÂ¸llen */
IGraphics->BltBitMapTags(BLITA_Source, alpha,
BLITA_SrcType, BLITT_CHUNKY,
BLITA_SrcBytesPerRow, width,
BLITA_Dest, ac->BitMap,
BLITA_Width, width,
BLITA_Height, height,
TAG_END );

/* Rahmenloses Fenster Ëffnen */
if((win = IIntuition->OpenWindowTags(NULL,
WA_Left, 1580,
WA_Top, 120,
WA_Width, width,
WA_Height, height,
WA_CloseGadget, FALSE,
WA_DragBar, FALSE,
WA_DepthGadget, FALSE,
WA_SizeGadget, FALSE,
WA_Borderless, TRUE,
WA_ToolBox, TRUE,
WA_AlphaClips, ac,
WA_CustomScreen,scr,
WA_Title, "Borderless window",
WA_IDCMP, IDCMP_MOUSEBUTTONS,
TAG_END )))
{
/* das komplette Fenster als dragable definieren */
struct Gadget draggad = { NULL, 0,0, width,height,
GFLG_GADGHNONE, 0, GTYP_WDRAGGING,
NULL,NULL,NULL,0,0,0,NULL };
win->FirstGadget = &draggad;

/* die Grafikdatei in das Fenster blitten */
IGraphics->BltBitMapRastPort(bitmap, 0, 0, win->RPort,
0, 0, width, height, MINTERM_ABC | MINTERM_ABNC);

/* warten auf CTRL-C zum Programm beenden */
IExec->Wait(SIGBREAKF_CTRL_C);

res = RETURN_OK;

/* Fenster schlieï¬en */
IIntuition->CloseWindow(win);
}
else IDOS->Printf("can not open window\n");
}
else IDOS->Printf("can not allocate alpha mask\n");

/* ClipRect freigeben; gibt auch ac->BitMap frei ! */
ILayers->FreeClipRect(&(scr->LayerInfo),ac);
}
else IDOS->Printf("can not allocate cliprect\n");
}
else IDOS->Printf("can not get (alpha) bitmaps\n");

/* BitMap Instance freigeben */
IIntuition->ReleaseBitMapInstance(instance);
}
else IDOS->Printf("can not get instance of picture\n");

/* Grafikdatei freigeben */
IIntuition->ReleaseBitMapSource(source);
}
else IDOS->Printf("loading picture file failed\n");

/* Bildschirm freigeben */
IIntuition->UnlockPubScreen(NULL,scr);
}
else IDOS->Printf("can not lock pubscreen\n");

IDOS->FreeArgs(rda);
}
else { IDOS->PrintFault(IDOS->IoErr(),"BorderlessWindow"); res = RETURN_ERROR; }
}
else IDOS->Printf("Program requires AmigaOS 4.1\n");

return res;
}
</syntaxhighlight>

Grab the test graphic here: [[Media:testpic.png|testpic.png]].

[[File:AF108_borderless_grab.png|frame|center]]

= Outlook =

You can look forward to the next issue, in which we will deal with datatypes. Do not expect any novelties regarding the program, but for the sake of completeness we should mention these options as well.

[[File:AF108_FensterLoch_grab.png|frame|center]]
With a hole in a window you can create funny effects, especially if you move the window around.

= Authors =

Written by Michael Christoph and Aleksandra Schmidt-Pendarovska 
Copyright (c) 2013 Michael Christoph