View source for Datatypes Library

= Introduction to the Datatypes Library =

The purpose of the datatypes
library is to provide software tools for handling data in an
object-oriented way. The object-oriented approach means that your
application can work with numerous data file standards without having
to worry about the complex details of each one. Instead you need
only understand the simple conventions of the datatypes library.

The datatypes library is built on Intuition's BOOPSI facility (BOOPSI
is an acronym for Basic Object-Oriented Programming System for
Intuition). Although not required, it is very helpful to know a
little about how BOOPSI works before trying to use the datatypes
library. For information on BOOPSI, refer to [[BOOPSI_-_Object_Oriented_Intuition|BOOPSI]].
Some familiarity with object-oriented theory and
practice is also helpful, though not required.

Since the datatypes library uses the TagItem structure for passing
parameters to functions, you will have to understand how TagItems
work before you can call the functions in the datatypes library. For
more information on TagItems refer to the [[Utility_Library|Utility Library]].

= Why Use the Datatypes Library? =

One practical benefit of the datatypes library is that it allows you
to quickly add support for IFF data files (this article will show you
how). However, the goals of the datatypes library are much more
ambitious than that.  Here's a summary:

* Consistent, simple handling of multiple data standards - Most of the details of dealing with the various data standards are hidden. Once you have learned how to handle one type of data with the datatypes library, you will find that the other types are handled in much the same way.

* Extensible - You can add your own types of data objects to those already supported by the datatypes library. Datatypes has functions that allow other applications to find out about and work with your data object, without having to understand the internal details of the data.

* Automatic support of IFF and clipboard - The initial version of the datatypes library (V39) provides support for 8SVX sound data and ILBM graphic data. These are the two most widely used data file standards on the Amiga. Developers who want to support these IFF standards no longer have to become IFF experts. Similarly, the datatypes library provides a consistent and easy-to-use interface to the Amiga's clipboard device to encourage data sharing between applications.

* Intuition gadget support - Because the datatypes library is implemented with BOOPSI, the data objects it handles can also be treated as gadgets. Gadget operations can be performed on data objects within Intuition's task context, the same as other BOOPSI gadgets.

* Automatic conversion from one format to another - Future versions of the datatypes library will support other types of data objects. Conversion from one format to another will be automatically handled by the library.

* Validation - Datatypes lets you easily check if a given file is a valid instance of one of the data objects it supports. For example, you can check to see if a file is a valid ILBM or not.

= Classes, Objects and Methods =

The jargon used to describe the datatypes library may be a little confusing if you have never worked with object-oriented systems before. For instance, the kinds of data supported by the library are divided into ''classes'' and ''sub-classes''.  The term ''class'' is used here in a familiar way; the members of a class simply have a common set of properties.  The members of a sub-class have all the properties of the parent class and additional properties specific to the sub-class.  (Each sub-class could be further broken down into sub-sub-classes and so on.)

{| class="wikitable"
| Class || Ungulate || Has hooves, can run.
|-
| Sub-class || Cow || Has udder, can be milked (also has hooves and can run).
|-
| Object || Daisy || An instance of class Cow; can run and can be milked.
|}

An actual instance of a class or sub-class is referred to as an ''object''. The term ''object'' is appropriate because in general we want to ignore the details of each individual case and concentrate instead on what we can do with an object based on its class. In the example above the Daisy object can run and can be milked. The operations that can be performed with an object are referred to as ''methods'' and the object is said to ''inherit'' the methods and other attributes of its parent class (which in turn inherits the methods and attributes of its parent class, if it has one).

The datatypes.library implements ''datatypesclass'' from which all other datatype classes inherit from. The following BOOPSI class diagram illustrates how the various datatypes classes relate to each other.

<center>
<classdiagram type="orderly" scale="60" dir="rl">
[gadgetclass]->[rootclass]
[datatypesclass]->[gadgetclass]
[sound.datatype]->[datatypesclass]
[picture.datatype]->[datatypesclass]
[text.datatype]->[datatypesclass]
[amigaguide.datatype]->[datatypesclass]
[animation.datatype]->[datatypesclass]
[8svx.datatype]->[sound.datatype]
[aiff.datatype]->[sound.datatype]
[anim.datatype]->[animation.datatype]
[ascii.datatype]->[text.datatype]
[bmp.datatype]->[picture.datatype]
[cdxl.datatype]->[animation.datatype]
[gif.datatype]->[picture.datatype]
[ilbm.datatype]->[picture.datatype]
[jpeg.datatype]->[picture.datatype]
[png.datatype]->[picture.datatype]
[tiff.datatype]->[picture.datatype]
[wav.datatype]->[sound.datatype]
</classdiagram>
</center>

{| class="wikitable"
|+ Table 1: Datatypes Library Object Classes
! Object Classes
! Autodoc File Showing the Methods Supported
! Type of Data Object
|-
| Picture class
| picture_dtc.doc
| IFF graphic image file
|-
| Sound class
| sound_dtc.doc
| IFF audio sample file
|-
| Text class
| text_dtc.doc
| ASCII characters
|-
| AmigaGuide class
| amigaguide_dtc.doc
| Hypertext databases
|-
| Animation class
| animation_dtc.doc
| Animations containing graphics and sound
|}

The examples programs listed below demonstrate how to perform some basic ''methods'' on ILBM and 8SVX class objects.

= Datatypes Class Attributes =

Datatype library classes have other attributes in addition to the
methods (operations) that they support.  For each attribute, there is
a corresponding TagItem defined in the datatypes library that you can
use to examine or set that attribute in a particular object

For example, picture objects have a display mode attribute.  The tag
that controls this attribute is named PDTA_ModeID and is described in
the Autodoc file picture_dtc.doc.  See the Autodoc files for each
class (as shown in Table 1) for a complete list of all class
attributes.

The class attribute descriptions in the include files also have a set
of codes that indicate the ''applicability'' of the attribute.  The
codes are as follows:

{| class="wikitable"
| I - Initialize
| You can initialize the attribute when the object is created
|-
| S - Set
| You can set the attribute to a new value after the object is created
|-
| G - Get
| You can get the value of the attribute after the object is created
|-
| N - Notify
| Changing the attribute triggers the object to send notification
|-
| U - Update
| Attribute can be set using the object's OM_UPDATE method
|}

These codes may seem a little mysterious until you have actually
tried using the datatypes library.  The N and U codes in particular
are for special applications that want to implement their own object
classes, an advanced topic beyond the scope of this article.

= Basic Functions of the Datatypes Library =

If all these new concepts seem a little daunting, rest assured; the datatypes library uses conventional C language function calls to get the job done. The calls you will be using most often are listed below. Notice that for each of these basic functions of datatypes library there is an equivalent BOOPSI call in the Intuition Library.

{| class="wikitable"
! Function Name
! Library
! Purpose
|-
| NewDTObject()<br/>NewObject()
| datatypes.library<br/>intuition.library
| Create a datatype object in memory from a file or clip
|-
| DisposeDTObject()<br/>DisposeObject()
| datatypes.library<br/>intuition.library
| Free an object created earlier with NewDTObject() (or NewObject() )
|-
| GetDTAttrs()<br/>GetAttr()
| datatypes.library<br/>intuition.library
| Get attributes of a datatype object
|-
| SetDTAttrs()<br/>SetAttrs()
| datatypes.library<br/>intuition.library
| Set attributes for a datatype object
|-
| DoDTMethod()<br/>IDoMethod()
| datatypes.library<br/>intuition.library
| Perform the given method (operation) with a datatype object
|}

There are also additional functions used to access DataType objects.

{| class="wikitable"
! Function Name
! Purpose
|-
| AddDTObject() || Add a DataType object to a window.
|-
| RefreshDTObjectA() || Refresh the rendering of a DataType object.
|-
| RemoveDTObject() || Remove a DataType object from a window.
|-
| GetDTMethods() || Get a list of the methods that a DataTypes object supports. Write, Copy, and Select are examples of methods that an object may support.
|-
| GetDTTriggerMethods() || Get a list of the trigger methods that a DataType object supports. An action like Play, Pause, and Resume are examples of trigger methods that an object may support.
|-
| PrintDTObject() || Asynchronously print a DataType object.
|-
| GetDTString() || Get the localized text string for a DataTypes text id. Useful for obtaining localized error messages.
|}

In a typical application the sequence of calls might be performed
like this:

# Use NewDTObject() to create an object in memory from given data.
# Get (or perhaps set) attributes of the object using GetDTAttr() (or SetDTAttrs() ).
# Perform ''methods'' (operations) with the object using DoDTMethod().
# Free the object and any memory or other resources it was using with the DisposeDTObject() call.

= Basic Structures of the Datatypes Library =

There are a lot of structures used with datatypes library function calls; too many to summarize in this article. However, here's a listing of the relevant include files that contain the structure definitions of interest to class users.

{| class="wikitable"
| <datatypes/datatypes.h>
| Group IDs, error numbers plus library overhead
|-
| <datatypes/datatypesclass.h>
| Defines datatype methods and associated structures
|-
| <datatypes/picture.h>
| Structures specific to the picture class
|-
| <datatypes/sound.h>
| Structures specific to the sound class
|-
| <datatypes/text.h>
| Structures specific to the text class
|-
| <libraries/amigaguide.h>
| Structures and methods for AmigaGuide databases
|-
| <intuition/classusr.h>
| Defines general BOOPSI object methods
|-
| <intuition/gadgetclass.h>
| Defines gadget methods and associated structures
|}

The two most important definitions in these include files appear in <intuition/classusr.h>. The objects used with datatypes library functions (and the BOOPSI functions in Intuition) are defined as follows:

<syntaxhighlight>
typedef ULONG   Object;     /* abstract handle */
</syntaxhighlight>

Since we want to treat objects as black boxes and don't really care how they are implemented, this definition is very appropriate. When a method is performed with an object, the parameter used to identify the method is a Msg structure defined as follows:

<syntaxhighlight>
typedef struct {
    ULONG MethodID;
    /* method-specific data goes here */
} *Msg;
</syntaxhighlight>

Some methods require more information than just the method identifier. Such methods have a custom structure defined in the include files.  All method structures, however, begin with a field that contains the method ID.

= Creating a DataType Object =

The DataTypes function NewDTObjectA() must be used to create a new DataType object.

<syntaxhighlight>
Object *dto = IDataTypes->NewDTObjectA (APTR name, struct TagItem *attrs);
</syntaxhighlight>

The pointer that NewDTObjectA() returns is a pointer to a BOOPSI object. Like other BOOPSI objects, DataType objects are "black boxes" and are not to be peeked and poked without using the provided interface.

To create a DataType object, NewDTObjectA() needs to know the where to obtain the data used to create the object. By default the name is treated as file name.

The attrs tag list is a list of tag/value pairs, each of which contains an initial value for an attribute. There are a number of attributes defined in <datatypes/datatypesclass.h> that can be used at creation time.

; DTA_SourceType
: Specify the type of the source data. The default is DTST_FILE.
:{| class="wikitable"
| DTST_RAM || Source data is in RAM.
|-
| DTST_FILE || Source data is a file. Name is the name of the file.
|-
| DTST_CLIPBOARD || Source data is in the clipboard. Name is the unit number. For example, (APTR)0, for clipboard unit zero.
|-
| DTST_HOTLINK || Reserved for future use.
|}

; DTA_Handle
: Can be used instead of the name field. If the source type is DTST_FILE then handle must be a valid BPTR file handle. If the source type is DTST_CLIPBOARD then handle must be a valid IFFHandle.

; DTA_DataType
: Can be used to specify the class for handling the data. Data must be a pointer to a valid DataType. This should only be used when attempting to create a new object that doesn't have source data, or could be handled by multiple classes (for example, could be used to force an object to be handled by the AmigaGuide class).

; DTA_GroupID
: If this tag is present, then the data must be of the specified type, or the object creation will fail with ERROR_OBJECT_WRONG_TYPE. This can be used by a Sound editor to ensure that only sounds can be loaded, for example.

There are additional attributes that can specified at creation time, but are dependant on the data type of the object being created. See the header files <datatypes/#?class.h> for more attributes.

The following attributes, which are defined in <intuition/gadgetclass.h>, are also valid.
{| class="wikitable"
! Tag !! Description
|-
| GA_Left || Specify the left edge of the gadget.
|-
| GA_RelRight || Specify the left edge of the gadget being relative to the right edge of the containing window.
|-
| GA_Top || Specify the top edge of the gadget.
|-
| GA_RelBottom || Specify the top edge of the gadget being relative to the bottom edge of the containing window.
|-
| GA_Width || Specify the width of the gadget.
|-
| GA_RelWidth || Specify the width of the gadget being relative to the width of the containing window.
|-
| GA_Height || Specify the heigh of the gadget.
|-
| GA_RelHeight || Specify the heigh of the gadget being relative to the height of the containing window.
|-
| GA_ID || Specify a ID associated with the gadget.
|-
| GA_UserData || Attach application data to the gadget.
|-
| GA_Immediate || Indicate that the application should be notified of gadget down events for this gadget.
|-
| GA_RelVerify || Indicate that the application should be notified of gadget up events for this gadget.
|-
| GA_Previous || For adding the gadget to a list of gadgets.
|-
| GA_DrawInfo || A pointer to a struct DrawInfo.
|}

In order for the application to receive information from the DataType object, it must set up a target for the notification attributes that the object sends out.

; ICA_TARGET
: Specify a target for the notification attributes that the DataType object sends out.

; ICA_MAP
: Specify an attribute mapping for the notification attributes that the DataType object sends out.

The usual method to obtain notification is to set up an ICA_TARGET of ICTARGET_IDCMP so that the application will receive the attributes via the IDCMP_IDCMPUPDATE Intuition message class. But it is also possible to set up another BOOPSI object as the receiver.

If NewDTObjectA() is successful, it returns a pointer to a DataType object. Otherwise it returns NULL and the reason for failure can be obtained using IoErr(). See the Autodocs for datatypes.library for more information.

= Obtaining Environment Information for a DataType =

In order to embed a DataType object in a window, it is neccessary to ask the object what its minimum environment is. For example, since the remap code doesn't handle remapping HAM pictures, they must be shown on a HAM screen, and therefore can't be added to a window that is on a non-HAM screen.

<syntaxhighlight>
ULONG modeid = INVALID_ID;
LONG nomwidth, nomheight;
BOOL useScreen = FALSE;
struct dtFrameBox dtf;
struct FrameInfo fri;

/* Get the attributes that we are interested in */
IDataTypes->GetDTAttrs(dto,
    /* Get the mode ID */
    PDTA_ModeID,    &modeid,

    /* Get the desired size */
    DTA_NominalHoriz, &nomwidth,
    DTA_NominalVert,  &nomheight,

    TAG_END);

/* Clear the structures */
IUtility->ClearMem(&dtf, sizeof (struct dtFrameBox));
IUtility->ClearMem(&fri, sizeof (struct FrameInfo));

/* Fill in the message */
dtf.MethodID          = DTM_FRAMEBOX;
dtf.dtf_FrameInfo     = &fri;
dtf.dtf_ContentsInfo  = &fri;
dtf.dtf_SizeFrameInfo = sizeof (struct FrameInfo);

/* Perform the frame method */
if (IDataTypes->DoDTMethodA (dto, NULL, NULL, (Msg) &dtf))
{
  /* Check to see if the object requires a HAM screen */
  if (fri.fri_PropertyFlags & DIPF_IS_HAM)
  {
      IDOS->Printf ("HAM\n");
      useScreen = TRUE;
  }
  /* Check to see if the object requires an ExtraHalfBrite screen */
  else if (fri.fri_PropertyFlags & DIPF_IS_EXTRAHALFBRITE)
  {
      IDOS->Printf ("ExtraHalfBrite\n");
      useScreen = TRUE;
  }
  /* A safety check to see if a screen is required */
  else if ((fri.fri_PropertyFlags == 0) && (modeid & 0x800) && (modeid != INVALID_ID))
  {
      IDOS->Printf ("ModeID=0x%08lx\n", modeid);
      useScreen = TRUE;
  }
}
else
{
  /* No special environment required, can be attached to any screen mode */
}
</syntaxhighlight>

= Adding a DataType Object to a Window =

A DataType object must be added to a window using the AddDTObject() function of DataTypes.

<syntaxhighlight>
LONG AddDTObject (struct Window *w, struct Requester *r, Object *dto, LONG pos)
</syntaxhighlight>

This function will add a DataTypes object to the existing gadget list for the specified window. The recommended value for pos is -1 which will cause the DataType object to be added to the end of the list.

DataType objects should not be added using the WA_Gadgets attribute to OpenWindowTagList() or by using the AddGList() function. There is special information that DataTypes requires that will not obtained if any method other than AddDTObject() is used.

When the DataType object is added to the window, the layout method for the object will be invoked. It is possible that the layout will take a while to perform, in that case the object will spawn a process to handle the layout asynchronously. In order to refresh the object's visual information, it is necessary to obtain IDCMP_IDCMPUPDATE messages from the object and refresh the object when a DTA_Sync attribute is received.

The following code fragment illustrates adding a DataType object to a window.

<syntaxhighlight>
Object *dto;

struct IntuiMessage *imsg;
struct Window *win;
ULONG sigr;

struct TagItem *tstate, *tags;
ULONG tidata;
ULONG errnum;

BOOL going = TRUE;

/* Set the pertinent attributes of the DataType object */
IDataTypes->SetDTAttrs (dto, NULL, NULL,

    /* Set the dimensions of the object */
    GA_Left,    win->BorderLeft,
    GA_Top,     win->BorderTop,
    GA_Width,   win->Width - win->BorderLeft - win->BorderRight,
    GA_Height,  win->Height - win->BorderTop - win->BorderBottom,

    /* Make sure we receive IDCMP_IDCMPUPDATE messages from
     * the object */
    ICA_TARGET, ICTARGET_IDCMP,
    TAG_END);

/* Add the object to the window */
IDataTypes->AddDTObject (win, NULL, dto, -1);

/* Refresh the DataType object */
IDataTypes->RefreshDTObjects (dto, win, NULL, NULL);

/* Keep going until we're told to stop */
while (going)
{
    /* Wait for an event */
    sigr = IExec->Wait ((1L << win->UserPort->mp_SigBit) | SIGBREAKF_CTRL_C);

    /* Did we get a break signal */
    if (sigr & SIGBREAKF_CTRL_C)
        going = FALSE;

    /* Pull Intuition messages */
    while (imsg = (struct IntuiMessage *) IExec->GetMsg (win->UserPort))
    {
        /* Handle each message */
        switch (imsg->Class)
        {
            case IDCMP_IDCMPUPDATE:
                /* Get a pointer to the attribute list */
                tstate = tags = (struct TagItem *) imsg->IAddress;

                /* Step through the attribute list */
                while (tag = IUtility->NextTagItem (&tstate))
                {
                    tidata = tag->ti_Data;
                    switch (tag->ti_Tag)
                    {
                        /* Change in busy state */
                        case DTA_Busy:
                            if (tidata)
                                IIntuition->SetWindowPointer (win, WA_BusyPointer, TRUE, TAG_END);
                            else
                                IIntuition->SetWindowPointer (win, WA_Pointer, NULL, TAG_END);
                            break;

                        /* Error message */
                        case DTA_ErrorLevel:
                            if (tidata)
                            {
                                errnum = IUtility->GetTagData (DTA_ErrorNumber, NULL, tags);
                                IDOS->PrintErrorMsg (errnum, (STRPTR) options[OPT_NAME]);
                            }
                            break;

                        /* Time to refresh */
                        case DTA_Sync:
                            /* Refresh the DataType object */
                            IDataTypes->RefreshDTObjects (dto, win, NULL, NULL);
                            break;
                    }
                }
                break;
        }

        /* Done with the message, so reply to it */
        IExec->ReplyMsg ((struct Message *) imsg);
    }
}
</syntaxhighlight>

= Removing a DataType Object from a Window =

A DataType object must be removed from the window using the RemoveDTObject() function.

<syntaxhighlight>
LONG RemoveDTObject (struct Window *w, Object *dto)
</syntaxhighlight>

This function removes the DataType object from the window's gadget list.

This is the only way that a DataType object should be removed from the window list. Using RemoveGList() is not supported, nor is removing the object manually.

= Setting an Existing DataType Object's Attributes =

An objects attributes are not necessarily static. An application can ask an object to set certain attributes using the SetDTAttrs() function.

<syntaxhighlight>
ULONG SetDTAttrsA (Object *dto, struct Window *w, struct Requester *r, struct TagItem *attrs)
</syntaxhighlight>

The return value is DataType object specific, but generally a non-zero value means that the object needs to be visually refreshed.

The following fragment illustrates how to set the current top values for a DataType object, using the VarArgs version of SetDTAttrsA().

<syntaxhighlight>
IDataTypes->SetDTAttrs(dto, window, NULL,
    DTA_TopVert,  0,
    DTA_TopHoriz, 0,
    TAG_END);
</syntaxhighlight>

This will cause the DataType object to update its vertical and horizontal top values. If the object has been added to a window, then the display will be updated accordingly.

Note that it is not OK to call SetGadgetAttrs() or SetAttrs() on a DataType object.

= Getting a DataType Object's Attributes =

The DataTypes function GetDTAttrsA() is used to obtain the values for a list of attributes from a DataType object.

<syntaxhighlight>
ULONG GetDTAttrsA (Object *dto, struct TagItem *attrs)
</syntaxhighlight>

Where dto is a pointer to a DataType object returned by NewDTObjectA().

And attrs is a TAG_END terminated array of attributes. Where the data element of each pair contains the address of the storage variable for that attribute.

This function will return a number that indicates that number of attributes that it was able to obtain. For example if four attributes asked for and GetDTAttrs returns a four, then all the attributes were obtained.

The following code fragment illustrates how to get the current top values
for a DataTypes object using the VarArgs form of GetDTAttrsA().

<syntaxhighlight>
LONG topv, toph;

if (IDataTypes->GetDTAttrs (dto, DTA_TopVert, &topv, DTA_TopHoriz, &toph, TAG_DONE) == 2)
{
    IDOS->Printf ("Top: vertical=%ld, horizontal=%ld\n", topv, toph);
}
else
{
    IDOS->Printf ("couldn't obtain the top values\n");
}
</syntaxhighlight>

= A Simple Datatypes Example =

The example program listed here should clarify some of the concepts
discussed so far.  Suppose you have a communications program and want
to add the capability of playing back a user-specified 8SVX sample
file for the bell sound (Ctrl-G).  The program below shows how to
play a sound with the datatypes library.

In this program, objects are of class 8SVX (a sub-class of the sound
datatype).  The method performed with the object is named DTM_TRIGGER
(described in the Autodoc file sound_dtc.doc).  The DTM_TRIGGER
method (with type set to STM_PLAY) causes a sampled sound to be
played on the Amiga's audio hardware.  Since the DTM_TRIGGER method
requires other information in addition to the method ID, a dtTrigger
structure is used.  This structure is defined in <datatypes/datatypesclass.h>.

Note that if the sound datatype is enhanced to support other types of
sound files in a future version of the Amiga OS, the code given here
will automatically support the new type.  This example expects the
file name and path to a sound file.

<syntaxhighlight>
; /* Compiled with SAS/C 6.56.  Run from CLI only.
sc DATA=NEAR NMINC STRMERGE NOSTKCHK IGNORE=73 dt.c
slink from lib:c.o dt.o TO dt LIBRARY lib:sc.lib lib:amiga.lib
quit ; */

#include <exec/types.h>
#include <datatypes/datatypesclass.h>  /* This includes other files we need */
#include <stdio.h>

#include <clib/exec_protos.h>          /* Prototypes for system functions */
#include <clib/intuition_protos.h>
#include <clib/datatypes_protos.h>

#ifdef LATTICE                         /* Disable SAS/C CTRL-C handling */
int CXBRK(void)    { return(0); }
int chkabort(void) { return(0); }
#endif




struct Library *IntuitionBase=NULL;    /* System library bases */
struct Library *DataTypesBase=NULL;

VOID main(int argc, char **argv)
{
APTR dtobject=NULL;        /* Pointer to a datatypes object */
struct dtTrigger mydtt;    /* A trigger structure for the DTM_TRIGGER method */
ULONG dores;               /* Variable for return values    */

if (IntuitionBase=OpenLibrary("intuition.library",39L))
   {
   if(DataTypesBase=OpenLibrary("datatypes.library",39L) )
      {
      if(argc > 1 ) /* CLI only, at least one argument please. */
         {
         /* Attempt to make an 8svx sound object from the file name the user */
         /* specified in the command line.  For a list of possible error     */
         /* returns, see the Autodocs for NewDTObjectA().  The group ID tag  */
         /* will allow only sound datatype files to be accepted for the call.*/
         if (dtobject = NewDTObject(argv[1], DTA_GroupID, GID_SOUND,
                                             TAG_END) )
            {
            mydtt.MethodID     = DTM_TRIGGER; /* Fill in the dtTrigger struct */
            mydtt.dtt_GInfo    = NULL;
            mydtt.dtt_Function = STM_PLAY;
            mydtt.dtt_Data     = NULL;

            /* The return value of the DTM_TRIGGER method used with the 8svx */
            /* sound datatype is undefined in V39.  This is likely to change */
            /* in future versions of the Amiga operating system.             */
            dores = DoDTMethodA(dtobject, NULL, NULL, &mydtt);

            /* Let the 8svx sound finish playing.  Currently (V39) there is  */
            /* no programmatic way to find out when it is finished playing.  */
            Wait(SIGBREAKF_CTRL_C);

            DisposeDTObject(dtobject);
            }
         else printf("Couldn't create new object or not a sound data file\n");

         }
      else printf("Give a file name too.\n");

      CloseLibrary(DataTypesBase);
      }
   else printf("Can't open datatypes library\n");

   CloseLibrary(IntuitionBase);
   }
else printf("Can't open V39 Intuition\n");
}
</syntaxhighlight>

In addition to playing back a sampled sound, the datatypes library
allows sound objects to become gadgets (the library includes default
imagery for a sound gadget).  Since all datatypes object classes are
implemented as a sub-class of the BOOPSI ''gadget'' class, they all
support the methods of gadget objects as described in the BOOPSI
chapter of the Libraries manual.

= Embedding DataTypes =

Since DataType objects are a sub-class of the Intuition Gadget class, DataType objects can be attached to an Intuition window in a similiar way that gadgets can be added to a window. DataTypes use a parallel set of functions because it requires additional information that the Intuition functions weren't able to provide.

Currently the handling of the data is limited to reading, writing, printing, viewing (audio or visual), and clipboard access. The MultiView utility is an example of an application that embeds DataType objects.

= Determining Data Type =

One of the main features of the DataTypes system is its ability to determine the data type of a block of data. This data block can reside in a file or the clipboard.

The following functions are used to determine the DataType of a data block:

{| class="wikitable"
| ObtainDataTypeA() || Obtain the DataType descriptor for a data block.
|-
| ReleaseDataType() || Release the DataType descriptor for a data block.
|}

The data type detection functions use the DataType structure.

<syntaxhighlight>
struct DataType
{
    struct Node            dtn_Node1;
    struct Node            dtn_Node2;
    struct DataTypeHeader *dtn_Header;
    struct List            dtn_ToolList;
    STRPTR                 dtn_FunctionName;
    struct TagItem        *dtn_AttrList;
    ULONG                  dtn_Length;
};
</syntaxhighlight>

The DataType structure is read-only. The only pertinent field is the dtn_Header field, which points to a DataTypeHeader structure.

<syntaxhighlight>
struct DataTypeHeader
{
    STRPTR   dth_Name;
    STRPTR   dth_BaseName;
    STRPTR   dth_Pattern;
    WORD    *dth_Mask;
    ULONG    dth_GroupID;
    ULONG    dth_ID;
    WORD     dth_MaskLen;
    WORD     dth_Pad;
    UWORD    dth_Flags;
    WORD     dth_Priority;
};
</syntaxhighlight>

The DataTypeHeader structure fields are as follows:

; dth_Name
: Descriptive name of the data type. For example, the description for an ILBM data type could possibly be "Amiga BitMap Picture".

; dth_BaseName
: This is the base name for the data type and is used to obtain the class that handles this data type.

; dth_GroupID
: This indicates the main type data that the object contains. Following are the possible values:
:{| class="wikitable"
| GID_SYSTEM || Fonts, Executables, Libraries, Devices, etc...
|-
| GID_TEXT || Formatted or unformatted text.
|-
| GID_DOCUMENT || Formatted text with embedded DataTypes (such as pictures).
|-
| GID_SOUND || Audio samples.
|-
| GID_INSTRUMENT || Audio samples used for playing music.
|-
| GID_MUSIC || Musical scores.
|-
| GID_PICTURE || Graphic picture or brush.
|-
| GID_ANIMATION || Moving picture or cartoon.
|-
| GID_MOVIE || Moving picture or cartoon with sound.
|}

; dth_ID
: This is an individual indentifier for the DataType. For IFF files it is the same as the FORM type, for example ILBM for an Amiga BitMap picture. For non-IFF files, it is the first four characters of dth_Name.

; dth_Flags
: The flags field contains, among other information, the coarse type of data. The type can be obtained by ANDing DTF_TYPE_MASK with this field.
:{| class="wikitable"
| DTF_IFF || Interchange File Format
|-
| DTF_BINARY || Non-readable characters
|-
| DTF_ASCII || Readable characters
|-
| DTF_MISC || Disks and drawers
|}

; dth_Pattern
; dth_Mask
; dth_MaskLen
; dth_Priority
: These fields are used by the detection code in datatypes.library for determining the data type. See the "Defining a DataType Descriptor" section for more information.

Following is a code fragment that shows how to determine the data type of a file. This fragment uses functions from datatypes.library, dos.library, and iffparse.library.

<syntaxhighlight>
    STRPTR name = "somefilename";
    BPTR lock;

    struct DataTypeHeader *dth;
    struct DataType *dtn;
    UBYTE idesc[5];
    STRPTR tdesc;
    STRPTR gdesc;
    UWORD ttype;

    /* Obtain a lock on the file that we want information on */
    if (lock = IDOS->Lock (name, ACCESS_READ))
    {
	/* Get a pointer to the appropriate DataType structure */
	if (dtn = IDataTypes->ObtainDataTypeA (DTST_FILE, (APTR)lock, NULL))
	{
	    /* Get a pointer to the DataTypeHeader structure */
	    dth = dtn->dtn_Header;

	    /* Get the coarse type */
	    ttype = dth->dth_Flags & DTF_TYPE_MASK;

	    /* Get a pointer to the text strings */
	    tdesc = IDataTypes->GetDTString (ttype + DTMSG_TYPE_OFFSET);
	    gdesc = IDataTypes->GetDTString (dth->dth_GroupID);

	    /* Convert the ID to a string. */
	    IIFFParse->IDtoStr (dth->dth_ID, idesc);

	    /* Display the information */
	    IDOS->Printf ("   Description: %s\n", dth->dth_Name);
	    IDOS->Printf ("     Base Name: %s\n", dth->dth_BaseName);
	    IDOS->Printf ("          Type: %d - %s\n", ttype, tdesc);
	    IDOS->Printf ("         Group: %s\n", gdesc);
	    IDOS->Printf ("            ID: %s\n", idesc);

	    /* Release the DataType structure now that we are done with it */
	    IDataTypes->ReleaseDataType (dtn);
	}

	/* Release the DOS lock on the file */
	IDOS->UnLock (lock);
    }
</syntaxhighlight>

= A Picture Class Example =

Here is a second, more complex example showing how to use all the datatypes library functions described so far. In this example, the objects used are of class ILBM, a sub-class of picture.

Two methods will be performed with the object, DTM_PROCLAYOUT and DTM_FRAMEBOX. Both these methods have associated structures (gpLayout and dtFrameBox respectively). DTM_PROCLAYOUT makes the object available within the context of your application task (as opposed to Intuition's).  DTM_FRAMEBOX queries the display environment required by the picture.

Other attributes of the picture are obtained with a call to GetDTAttrs() and then a matching Intuition screen is created and the ILBM object is displayed. This example expects the file and path name of a picture file.

<syntaxhighlight>
; /* Compiled with SAS/C 6.56.  Run from CLI only.
sc DATA=NEAR NMINC STRMERGE NOSTKCHK IGNORE=73 dtpic.c
slink from lib:c.o dtpic.o TO dtpic LIBRARY lib:sc.lib lib:amiga.lib
quit ; */

#include <exec/types.h>
#include <datatypes/datatypes.h>      /* Datatypes definitions we need */
#include <datatypes/pictureclass.h>
#include <stdio.h>

#include <clib/exec_protos.h>         /* Prototypes for system functions */
#include <clib/intuition_protos.h>
#include <clib/alib_protos.h>
#include <clib/datatypes_protos.h>
#include <clib/graphics_protos.h>

#ifdef LATTICE
int CXBRK(void)    { return(0); }     /* Disable SAS/C CTRL-C handling */
int chkabort(void) { return(0); }
#endif

struct Library *IntuitionBase=NULL;   /* System library bases */
struct Library *GfxBase=NULL;
struct Library *DataTypesBase=NULL;

VOID main(int argc, char **argv)
{
APTR dtobject=NULL;                   /* Pointer to a datatypes object       */
ULONG res;                            /* Variable for function return values */
struct dtFrameBox mydtFrameBox;       /* Use this with DTM_FRAMEBOX method   */
struct FrameInfo myFrameInfo;         /* For info returned from DTM_FRAMEBOX */
struct gpLayout mygpLayout;           /* Use this with DTM_PROCLAYOUT method */

ULONG modeID = INVALID_ID;            /* Variables for storing the display */
struct Screen *myScreen=NULL;         /* environment information obtained  */
struct BitMap *bm = NULL;             /* the datatype object.              */
ULONG *cregs = NULL;
ULONG i,r,g,b,numcolors;

if (IntuitionBase=OpenLibrary("intuition.library",39L))
  {
  if (GfxBase=OpenLibrary("graphics.library",39L))
    {
    if(DataTypesBase=OpenLibrary("datatypes.library",0L))
        {
        if(argc > 1 ) /* CLI only, at least one argument please.  */
            {
            /* Attempt to create a picture object in memory from the file    */
            /* name given by the user in the command line.  If we wanted to  */
            /* show the picture in a screen set up ahead of time, we could   */
            /* set PDTA_Remap to TRUE and provide a pointer to the screen    */
            /* with the PDTA_Screen tag (datatypes.library handles the rest).*/
            /* However in this case we want to first find out the attributes */
            /* of the picture object and set up a matching screen and do the */
            /* remapping later.  Therefore PDTA_Remap is set to false.       */
            /* The group ID tag ensures that we get only a picture file type.*/
            if (dtobject = NewDTObject(argv[1], PDTA_Remap,  FALSE,
                                                DTA_GroupID, GID_PICTURE,
                                                TAG_END) )
                {
                /* Here we want to find the display environment required by  */
                /* this picture.  To do that, perform the DTM_FRAMEBOX method */
                /* on the object.  The datatypes library fills in the struct */
                /* FrameBox you give it with the info on the display needed.  */
                mydtFrameBox.MethodID         = DTM_FRAMEBOX;
                mydtFrameBox.dtf_GInfo        = NULL;
                mydtFrameBox.dtf_ContentsInfo = NULL;
                mydtFrameBox.dtf_FrameInfo    = &myFrameInfo;
                mydtFrameBox.dtf_SizeFrameInfo= sizeof (struct FrameInfo);
                mydtFrameBox.dtf_FrameFlags   = 0L;

                /* The return value from DTM_FRAMEBOX is currently undefined */
                res = DoMethodA(dtobject, &mydtFrameBox);

                /* OK, now do the layout (remap) of the object on our process */
                mygpLayout.MethodID   = DTM_PROCLAYOUT;
                mygpLayout.gpl_GInfo  = NULL;
                mygpLayout.gpl_Initial= 1L;

                /* The return value of DTM_PROCLAYOUT is non-zero for success */
                if( res = DoMethodA(dtobject, &mygpLayout) )
                   {
                   /* Get the attributes of this picture object.  You could  */
                   /* use a series of GetAttr() function calls here instead.  */
                   res = GetDTAttrs(dtobject, PDTA_ModeID, &modeID,
                                              PDTA_CRegs, &cregs,
                                              PDTA_BitMap, &bm,
                                              TAG_END);

                   /* Did we get all threee attributes? */
                   if( (modeID!=INVALID_ID) && (cregs) && (bm) )
                       {
                       /* Open a screen that matches the picture object */
                       if( myScreen = OpenScreenTags( NULL,
                           SA_Width,     myFrameInfo.fri_Dimensions.Width,
                           SA_Height,    myFrameInfo.fri_Dimensions.Height,
                           SA_Depth,     myFrameInfo.fri_Dimensions.Depth,
                           SA_DisplayID, modeID,
                           SA_BitMap,    bm,
                           TAG_END) )
                           {
                           /* Now fill in the color registers for this screen */
                           numcolors = 2<<(myFrameInfo.fri_Dimensions.Depth-1);
                           for( i=0; i < numcolors; i++ )
                              {
                              r = cregs[i * 3 + 0];
                              g = cregs[i * 3 + 1];
                              b = cregs[i * 3 + 2];
                              SetRGB32(&myScreen->ViewPort, i, r, g, b);
                              }

                           printf("Ctrl-C in this window to quit\n");
                           /* Wait for the user to have a look...  */
                           Wait(SIGBREAKF_CTRL_C);

                           CloseScreen(myScreen);
                           }
                       else printf("Couldn't open required screen\n");
                       }
                   else printf("Couldn't get picture attributes\n");

                  DisposeDTObject(dtobject);
                  }
               else printf("Couldn't perform PROC_LAYOUT\n");
               }
            else printf("Couldn't create new object or not a picture file\n");
            }
        else printf("Give a file name too.\n");

        CloseLibrary(DataTypesBase);
        }
    else printf("Can't open datatypes library\n");

    CloseLibrary(GfxBase);
    }
  else printf("Can't open V39 graphics\n");

  CloseLibrary(IntuitionBase);
  }
else printf("Can't open V39 Intuition\n");
}
</syntaxhighlight>

As with 8SVX objects, the datatypes library allows ILBM objects to be treated as gadgets. Remember that all datatypes object classes a sub-class of the BOOPSI ''gadget'' class and therefore support the
gadget methods described in [[BOOPSI_-_Object_Oriented_Intuition|the BOOPSI section]].

= Writing A Sub-Class =

For each of the DataType categories, there is a class that handles the data. Handlers for explicit data are sub-classes under the appropriate class. For example, a class that handles ILBM pictures would be a sub-class of the Picture class.

In order to fully understand the class concept used by DataTypes it helps to have a basic understanding of BOOPSI.

A sub-class must provide an OM_NEW method that converts the source data into the data format required by the super-class.  The sub-class must optionally have a OM_DISPOSE method that discards any of the data constructed in the OM_NEW method. All other methods must be passed to the super-class.

Following is a listing of a example class dispatcher for a sub-class of the picture class:

<syntaxhighlight>
uint32 Dispatch(Class *cl, Object *o, Msg msg)
{
    struct ClassBase *cb = (struct ClassBase *) cl->cl_UserData;
    uint32 retval;

    switch (msg->MethodID)
    {
        case OM_NEW:
            if (retval = IIntuition->IDoSuperMethodA(cl, o, msg))
            {
                /* Convert the source data to required data format */
                if (!GetObjectData (cb, cl, (Object *)retval,
                             ((struct opSet *) msg)->ops_AttrList))
                {
                    /* Force disposal of the object */
                    IIntuition->ICoerceMethod (cl, (Object *) retval, OM_DISPOSE);
                    retval = NULL;
                }
            }
            break;

        /* Let the superclass handle everything else */
        default:
            retval = (uint32) IIntuition->IDoSuperMethodA (cl, o, msg);
            break;
    }

    return (retval);
}
</syntaxhighlight>

== Obtaining a Handle to the Source Data ==

The first step that a class has to perform in order to convert the source data, is to get a handle on the data. This is obtained by passing the DTA_Handle tag to the super-class using the OM_GET method. For example:

<syntaxhighlight>
Object *o;
BPTR fh;

IDataTypes->GetDTAttrs(o, DTA_Handle, &fh, TAG_END);
</syntaxhighlight>

If the source Type is DTF_IFF, then DTA_Handle points to a struct IFFHandle that is already initialized and opened for reading, otherwise the handle points to a BPTR file handle.

== Handling Errors ==

Whenever an error occurs and the class is unable to continue converting the data, then it must set an appropriate error using the DOS SetIoErr() function and the <dos/dos.h> error codes or the error codes defined in <datatypes/datatypes.h>.

For example, if the class is unable to allocate memory:

<syntaxhighlight>
if (buf = IExec->AllocVecTags(size, AVT_ClearWithValue, 0, TAG_END))
    {
	... continue with conversion ...
    }
    else
    {
	IDOS->SetIoErr (ERROR_NO_FREE_STORE);
</syntaxhighlight>

== Data Format ==

The following sections outline the required data format for each of the main object types.

=== Picture Class ===

The picture class is the super-class for any static graphic classes. The structures and tags used by this class are defined in <datatypes/pictureclass.h>.

A picture sub-class must fill out a BitMapHeader structure as well as provide a Mode ID, a BitMap and a ColorMap during the OM_NEW method of the class.  There is no need to provide any other methods, as the remainder is handled by the picture class itself.

The picture sub-class needs to fill in any fields of the BitMapHeader structure that the class has data for. This will ensure that the picture data can then be saved to a file or copied to the clipboard.

<syntaxhighlight>
struct BitMapHeader *bmh;

/* Obtain a pointer to the BitMapHeader structure from the picture class */
if (IDataTypes->GetDTAttrs (dto, PDTA_BitMapHeader, &bmh, TAG_END) && bmh)
{
  /* Fill in some fields */
  bmh->bmh_Width  = 640;
  bmh->bmh_Height = 200;
  bmh->bmh_Depth  = 2;
}
</syntaxhighlight>

Before manipulating any color information, the picture sub-class must first tell the picture class how many colors it has, so that the information required for color remapping can be established.

<syntaxhighlight>
IDataTypes->SetDTAttrs (dto, PDTA_NumColors, ncolors, TAG_END);
</syntaxhighlight>

After the number of colors have been established, the palette information can be filled in for the picture. The following fragment illustrates filling in the palette information.

<syntaxhighlight>
struct ColorRegister *cmap;
int16 n, ncolors;
int32 *cregs;

/* Get a pointer to the color registers that need to be
 * filled in */
IDataTypes->GetDTAttrs (dto,
  PDTA_ColorRegisters, &cmap,
  PDTA_CRegs, &cregs,
  TAG_END);

/* Set the color information */
for (n = 0; n < ncolors; n++)
{
  if (IDOS->Read (fh, &rgb, QSIZE) == QSIZE)
  {
    /* Set the master color table */
    cmap->red   = rgb.rgbRed;
    cmap->green = rgb.rgbGreen;
    cmap->blue  = rgb.rgbBlue;
    cmap++;

    /* Set the color table used for remapping */
    cregs[n * 3 + 0] = rgb.rgbRed   << 24;
    cregs[n * 3 + 1] = rgb.rgbGreen << 24;
    cregs[n * 3 + 2] = rgb.rgbBlue  << 24;
  }
  else
  {
    /* Indicate that we encountered an error. DOS Read
     * will have already filled in the IoErr() value */
    return FALSE;
  }
}
</syntaxhighlight>

The picture class must get the actual picture information in standard Amiga bitmap format. If the bitmap is allocated using the graphics AllocBitMap() function, then the picture class can dispose of the bitmap at OM_DISPOSE time.

<syntaxhighlight>
struct BitMap *bm;

if (bm = IGraphics->AllocBitMap (bmh->bmh_Width, bmh->bmh_Height, bmh->bmh_Depth, BMF_CLEAR, NULL))
{
  /* Tell the picture class about the picture data */
  IDataTypes->SetDTAttrsA (dto, PDTA_BitMap, bm, TAG_END);
}
else
{
  /* Indicate the error and that we encountered an error */
  IDOS->SetIoErr (ERROR_NO_FREE_STORE);
  return FALSE;
}
</syntaxhighlight>

A picture sub-class needs to provide the following fields to the super-class, during the OM_NEW method:

{| class="wikitable"
| DTA_NominalHoriz || (int32) Set to the width of the picture.
|-
| DTA_NominalVert || (int32) Set to the height of the picture.
|-
| PDTA_ModeID || (uint32) A valid mode ID for the BitMap.
|-
| DTA_ObjName || (STRPTR) The name, or title, of the picture
|-
| DTA_ObjAuthor || (STRPTR) The author of the picture.
|-
| DTA_ObjAnnotation || (STRPTR) Notes on the picture.
|-
| DTA_ObjCopyright || (STRPTR) Copyright notice for the picture.
|-
| DTA_ObjVersion || (STRPTR) Version of the picture.
|}

If a picture sub-class uses something other than AllocBitMap() to allocate the bitmap, then it must free the bitmap itself. This is done by implementing an OM_DISPOSE method for the sub-class.

<syntaxhighlight>
uint32 Dispatch (Class *cl, Object *o, Msg msg)
{
  struct ClassBase *cb = (struct ClassBase *) cl->cl_UserData;
  struct localData *lod;
  uint32 retval;

  switch (msg->MethodID)
  {
      case OM_NEW:
        /* ... */
        break;

      case OM_DISPOSE:
        /* Get a pointer to our object data */
        lod = INST_DATA (cl, o);

        /* Tell the picture class that it doesn't have a
         * bitmap to free any more */
        IDataTypes->SetDTAttrs (o, PDTA_BitMap, NULL, TAG_DONE);

        /* Free the bitmap ourself */
        myfreebitmap (lod->lod_BitMap);

      /* Let the superclass handle everything else */
      default:
        retval = (uint32) IIntuition->DoSuperMethodA (cl, o, msg);
        break;
  }

  return retval;
}
</syntaxhighlight>

=== Sound Class ===

The sound class is the super-class for any sampled audio classes. The structures and tags used by this class are defined in
<datatypes/soundclass.h>.

A sound sub-class needs to provide the following fields to the super-class, during the OM_NEW method:

{| class="wikitable"
| SDTA_Sample || (uint8 *) 8-bit sound data. The sound class will FreeVec() the sample data.
|-
| SDTA_SampleLength || (uint32) Number of 8-bit bytes in the sound data.
|-
| SDTA_Volume || (uint16) Number ranging from 0 being the quietest to 64 being the loudest.
|-
| SDTA_Period || (uint16) Amount of time to play the sound.
|-
| SDTA_Cycles || (uint16) Number of times to play the sound. 0 being an infinite loop.
|-
| DTA_ObjName || (STRPTR) The name, or title, of the sound
|-
| DTA_ObjAuthor || (STRPTR) The author of the sound.
|-
| DTA_ObjAnnotation || (STRPTR) Notes on the sound.
|-
| DTA_ObjCopyright || (STRPTR) Copyright notice for the sound.
|-
| DTA_ObjVersion || (STRPTR) Version of the sound.
|}

No methods other OM_NEW are need, as the remainder is handled by the sound class itself.

The sound sub-class also needs to fill in any fields of the VoiceHeader structure that the class has data for. This will ensure that the sound data can then be saved to a file or copied to the clipboard.

<syntaxhighlight>
struct VoiceHeader *vh;

/* Obtain a pointer to the VoiceHeader structure from the sound class */
if (IDataTypes->GetDTAttrs (dto, SDTA_VoiceHeader, &vh, TAG_END) && vh)
{
  /* Fill in some fields */
  vh->vh_Octaves     = 1;
  vh->vh_Compression = 0;
  vh->vh_Volume      = 63;
}
</syntaxhighlight>

If a sound sub-class uses something other than AllocVec() to allocate the sound data, then it must free the sample itself. This is done by implementing an OM_DISPOSE method for the sub-class.

<syntaxhighlight>
uint32 Dispatch (Class *cl, Object *o, Msg msg)
{
  struct ClassBase *cb = (struct ClassBase *) cl->cl_UserData;
  struct localData *lod;
  uint32 retval;

  switch (msg->MethodID)
  {
    case OM_NEW:
      /* ... */
      break;

    case OM_DISPOSE:
      /* Get a pointer to our object data */
      lod = INST_DATA (cl, o);

      /* Tell the sound class that it doesn't have a
       * sample to free any more */
      IDataTypes->SetDTAttrs (o, SDTA_Sample, NULL, TAG_END);

      /* Free the sample ourself */
      IExec->FreeVec(lod->lod_Sample);

      /* Let the superclass handle everything else */
    default:
      retval = (uint32) IIntuition->IDoSuperMethodA (cl, o, msg);
      break;
  }

  return retval;
}
</syntaxhighlight>

=== Text Class ===

The text class is the super-class for any formatted or non-formatted text classes. The structures and tags used by this class are defined in <datatypes/textclass.h>.

The text class provides the sub-class with a buffer that contains the text data. The sub-class must then provide the text class with a list of Line segments during the layout method. This Line list should only be created at gpl_Initial time, unless the TDTA_WordWrap attribute is TRUE.

<syntaxhighlight>
struct Line
{
  struct MinNode ln_Link;
  STRPTR         ln_Text;
  ULONG		 ln_TextLen;
  UWORD		 ln_XOffset;
  UWORD		 ln_YOffset;
  UWORD		 ln_Width;
  UWORD		 ln_Height;
  UWORD		 ln_Flags;
  BYTE		 ln_FgPen;
  BYTE		 ln_BgPen;
  ULONG		 ln_Style;
  APTR		 ln_Data;
};
</syntaxhighlight>

The Line structure fields are as follows:

;ln_Link
: MinNode used to link to the line list.

; ln_Text
: Pointer to the text for this line segment.

; ln_TextLen
: Number of bytes of text in this line segment.

; ln_XOffset
: Left pixel offset from the left edge of the object for this line segment.

; ln_YOffset
: Top pixel offset from the top edge of the object for this line segment.

; ln_Width
: Width of the line segment in pixels.

; ln_Height
: Height of the line segment in pixels.

; ln_Flags
: Control flags for this line segment.
:: LNF_LF -- Used to indicate that this segment is the end of a line.

; ln_FgPen
: Pen to use for the foreground (the text color) for this line segment.

; ln_BgPen
: Pen to use for the background color for this line segment.

; ln_Style
: Text attribute soft style to use for this line segment.

As each Line segment is allocated it must be added to the Line list.

<syntaxhighlight>
struct List *linelist;
struct Line *line;

/* Get a pointer to the line list */
if (IDataTypes->GetDTAttrs (o, TDTA_LineList, (uint32) &linelist, TAG_END) && linelist)
{
  /* Create a Line segment */
  if (line = AllocVecTags(sizeof (struct Line), AVT_ClearWithValue, 0, TAG_END))
  {
    /* Add it to the list */
    IExec->AddTail (linelist, (struct Node *)&line->ln_Link);
  }
}
</syntaxhighlight>

Currently, this is the hardest class to sub-class, due to the number of methods that must be implemented. Following is the shell for a dispatcher and the layout method for a text sub-class.

<syntaxhighlight>
struct localData
{
  VOID  *lod_Pool;
  uint32 lod_Flags;
};

uint32 Dispatch (Class * cl, Object * o, Msg msg)
{
    struct ClassBase *cb = (struct ClassBase *) cl->cl_UserData;
    struct localData *lod;
    struct List *linelist;
    uint32G retval = 0;

    switch (msg->MethodID)
    {
        case OM_NEW:
            if (retval = IIntuition->IDoSuperMethodA (cl, o, msg))
            {
                uint32 len, estlines, poolsize;
                BOOL success = FALSE;
                STRPTR buffer;

                /* Get a pointer to the object data */
                lod = INST_DATA (cl, (Object *) retval);

                /* Get the attributes that we need to determine memory pool size */
                IDataTypes->GetDTAttrs ((Object *) retval,
                             TDTA_Buffer,    &buffer,
                             TDTA_BufferLen, &len,
                             TAG_END);

                 /* Make sure we have a text buffer */
                 if (buffer && len)
                 {
                     /* Estimate the pool size that we will need */
                     estlines = (len / 80) + 1;
                     estlines = (estlines > 200) ? 200 : estlines;
                     poolsize = sizeof (struct Line) * estlines;

                     /* Create a memory pool for the line list */
                     lod->lod_Pool = IExec->AllocSysObjectTags(ASOT_MEMPOOL,
                         ASOPOOL_MFlags, MEMF_SHARED | MEMF_CLEAR,
                         ASOPOOL_Puddle, poolsize,
                         ASOPOOL_Threshold, poolsize,
                         TAG_END);
                     if (lod->lod_Pool != NULL)
                         success = TRUE;
                     else
                         IDOS->SetIoErr (ERROR_NO_FREE_STORE);
                 }
                 else
                 {
                     /* Indicate that something was missing that we needed */
                     IDOS->SetIoErr (ERROR_REQUIRED_ARG_MISSING);
                 }

                 if (!success)
                 {
                     IIntuition->ICoerceMethod (cl, (Object *) retval, OM_DISPOSE);
                     retval = NULL;
                 }
             }
             break;

         case OM_UPDATE:
         case OM_SET:
             /* Pass the attributes to the text class and force a refresh if we need it */
             if ((retval = IIntuition->IDoSuperMethodA (cl, o, msg)) && (OCLASS (o) == cl))
             {
                 struct RastPort *rp;

                 /* Get a pointer to the rastport */
                 if (rp = IGraphics->ObtainGIRPort (((struct opSet *) msg)->ops_GInfo))
                 {
                     IIntuition->DoRender(o, ((struct opSet *) msg)->ops_GInfo, GREDRAW_UPDATE);

                     /* Release the temporary rastport */
                     IGraphics->ReleaseGIRPort (rp);
                 }
                 retval = 0;
             }
             break;

         case GM_LAYOUT:
             /* Tell everyone that we are busy doing things */
             notifyAttrChanges (o, ((struct gpLayout *) msg)->gpl_GInfo, NULL,
                                GA_ID, G(o)->GadgetID,
                                DTA_Busy,  TRUE,
                                TAG_END);

             /* Let the super-class partake */
             retval = (uint32) IIntuition->IDoSuperMethodA (cl, o, msg);

             /* We need to do this one asynchronously */
             retval += IDataTypes->DoAsyncLayout (o, (struct gpLayout *) msg);
             break;

         case DTM_PROCLAYOUT:
             /* Tell everyone that we are busy doing things */
             notifyAttrChanges (o, ((struct gpLayout *) msg)->gpl_GInfo, NULL,
                                GA_ID, G(o)->GadgetID,
                                DTA_Busy,  TRUE,
                                TAG_END);

             /* Let the super-class partake and then fall through to our layout method */
             retval = (uint32) IDataTypes->DoSuperMethodA (cl, o, msg);

         case DTM_ASYNCLAYOUT:
             /* Layout the text */
             retval = layoutMethod (cb, cl, o, (struct gpLayout *) msg);
             break;

         case OM_DISPOSE:
             /* Get a pointer to our object data */
             lod = INST_DATA (cl, o);

             /* Don't let the super class free the line list */
             if (IIntuition->GetDTAttrs (o, TDTA_LineList, &linelist, TAG_END) && linelist)
                 IExec->NewList (linelist);

             /* Delete the line pool */
             IExec->FreeSysObject(ASOT_MEMPOOL, lod->lod_Pool);

         /* Let the superclass handle everything else */
         default:
             retval = (uint32) IIntuition->DoSuperMethodA (cl, o, msg);
             break;
     }

     return (retval);
 }

 uint32 layoutMethod (struct ClassBase *cb, Class * cl, Object * o, struct gpLayout * gpl)
 {
     struct DTSpecialInfo *si = (struct DTSpecialInfo *) G (o)->SpecialInfo;
     struct localData *lod = INST_DATA (cl, o);
     uint32 visible = 0, total = 0;
     struct RastPort trp;
     uint32 hunit = 1;
     uint32 bsig = 0;

     /* Switches */
     BOOL linefeed = FALSE;
     BOOL newseg = FALSE;
     BOOL abort = FALSE;

     /* Attributes obtained from super-class */
     struct TextAttr *tattr;
     struct TextFont *font;
     struct List *linelist;
     struct IBox *domain;
     uint32 wrap = FALSE;
     uint32 bufferlen;
     STRPTR buffer;
     STRPTR title;

     /* Line information */
     uint32 num, offset, swidth;
     uint32 anchor, newanchor;
     uint32 style = FS_NORMAL;
     struct Line *line;
     uint32 yoffset = 0;
     uint8 fgpen = 1;
     uint8 bgpen = 0;
     uint32 tabspace;
     uint32 numtabs;
     uint32 i, j;

     uint32 nomwidth, nomheight;

     /* Get all the attributes that we are going to need for a successful layout */
     if (IDataTypes->GetDTAttrs (o,
                          DTA_TextAttr,  &tattr,
                          DTA_TextFont,  &font,
                          DTA_Domain,    &domain,
                          DTA_ObjName,   &title,
                          TDTA_Buffer,   &buffer,
                          TDTA_BufferLen,&bufferlen,
                          TDTA_LineList, &linelist,
                          TDTA_WordWrap, &wrap,
                          TAG_END) == 8)
     {
         /* Lock the global object data so that nobody else can manipulate it */
         IExec->ObtainSemaphore (&(si->si_Lock));

         /* Make sure we have a buffer */
         if (buffer)
         {
             /* Initialize the temporary RastPort */
             IGraphics->InitRastPort (&trp);
             IGraphics->SetFont (&trp, font);

             /* Calculate the nominal size */
             nomheight = (ULONG) (24 * font->tf_YSize);
             nomwidth  = (ULONG) (80 * font->tf_XSize);

             /* Calculate the tab space */
             tabspace = font->tf_XSize * 8;

             /* We only need to perform layout if we are doing word wrap, or this
              * is the initial layout call */
             if (wrap || gpl->gpl_Initial)
             {
                 /* Delete the old line list */
                 while (line = (struct Line *) IExec->RemHead (linelist))
                     IExec->FreePooled (lod->lod_Pool, line, sizeof (struct Line));

                 /* Step through the text buffer */
                 for (i = offset = num = numtabs = 0;
                      (i <= bufferlen) && (bsig == 0) && !abort;
                      i++)
                 {
                     /* Check for end of line */
                     if (buffer[i]==13 && buffer[i+1]==10)
                     {
                         newseg = linefeed = TRUE;
                         newanchor = i + 2;
                         i++;
                     }
                     /* Check for end of page */
                     else if (buffer[i] == 12)
                     {
                         newseg = linefeed = TRUE;
                         newanchor = i + 1;
                     }
                     /* Check for tab */
                     else if (buffer[i] == 9)
                     {
                         /* See if we need to terminate a line segment */
                         if ((numtabs == 0) && num)
                             newseg = TRUE;
                         numtabs++;
                     }
                     else
                     {
                         /* See if we have any TABs that we need to finish out */
                         if (numtabs)
                         {
                             offset += (((offset / tabspace) + 1) * tabspace) - offset;
                             num = numtabs = 0;
                             anchor = i;
                         }

                         /* Compute the width of the line. */
                         swidth = IGraphics->TextLength (&trp, &buffer[anchor], num+1);
                         if (offset + swidth > domain->Width)
                         {
                             /* Search for a whitespace character */
                             for (j = i; (j >= anchor) && !newseg; j--)
                             {
                                 if (buffer[j] == ' ')
                                 {
                                     num -= (i - j);
                                     newseg = TRUE;
                                     i = j + 1;
                                 }
                             }

                             newseg = linefeed = TRUE;
                             newanchor = i;
                             i--;
                         }
                         else
                         {
                             num++;
                         }
                     }

                     /* Time for a new text segment yet? */
                     if (newseg)
                     {
                         /* Allocate a new line segment from our memory pool */
                         if (line = IExec->AllocPooled (lod->lod_Pool, sizeof (struct Line)))
                         {
                             swidth = IGraphics->TextLength (&trp, &buffer[anchor], num);
                             line->ln_Text    = &buffer[anchor];
                             line->ln_TextLen = num;
                             line->ln_XOffset = offset;
                             line->ln_YOffset = yoffset + font->tf_Baseline;
                             line->ln_Width   = swidth;
                             line->ln_Height  = font->tf_YSize;
                             line->ln_Flags   = (linefeed) ? LNF_LF : NULL;
                             line->ln_FgPen   = fgpen;
                             line->ln_BgPen   = bgpen;
                             line->ln_Style   = style;
                             line->ln_Data    = NULL;

                             /* Add the line to the list */
                             IExec->AddTail (linelist, (struct Node *) line);

                             /* Increment the line count */
                             if (linefeed)
                             {
                                 yoffset += font->tf_YSize;
                                 offset = 0;
                                 total++;
                             }
                             else
                             {
                                 /* Increment the offset */
                                 offset += swidth;
                             }
                         }
                         else
                         {
                             abort = TRUE;
                         }

                         /* Clear the variables */
                         newseg = linefeed = FALSE;
                         anchor = newanchor;
                         num = 0;

                         /* Check to see if layout has been aborted */
                         bsig = IDOS->CheckSignal (SIGBREAKF_CTRL_C);
                     }
                 }
             }
             else
             {
                 /* No layout to perform */
                 total = si->si_TotVert;
             }
         }

         /* Compute the lines and columns type information */
         si->si_VertUnit  = font->tf_YSize;
         si->si_VisVert   = visible = domain->Height / si->si_VertUnit;
         si->si_TotVert   = total;

         si->si_HorizUnit = hunit = 1;
         si->si_VisHoriz  = (int32) domain->Width / hunit;
         si->si_TotHoriz  = domain->Width;

         /* Release the global data lock */
         IExec->ReleaseSemaphore (&si->si_Lock);

         /* Were we aborted? */
         if (bsig == 0)
         {
             /* Not aborted, so tell the world of our newest attributes */
             notifyAttrChanges (o, gpl->gpl_GInfo, NULL,
                                GA_ID,                   G(o)->GadgetID,

                                DTA_VisibleVert,         visible,
                                DTA_TotalVert,           total,
                                DTA_NominalVert,         nomheight,
                                DTA_VertUnit,            font->tf_YSize,

                                DTA_VisibleHoriz,        (uint32) (domain->Width / hunit),
                                DTA_TotalHoriz,          domain->Width,
                                DTA_NominalHoriz,        nomwidth,
                                DTA_HorizUnit,           hunit,

                                DTA_Title,               title,
                                DTA_Busy,                FALSE,
                                DTA_Sync,                TRUE,
                                TAG_END);
         }
     }
     
     return total;
}
</syntaxhighlight>