Programming AmigaOS in C

11. Datatypes

When the first Amiga came out in 1985 there were very few file formats available and very few standard formats (GIF didn't appear until 1987 and JPEG until 1992). So Commodore and Electronics Arts developed the IFF (Interchangable File Format) which covered pictures (ILBM), sound (8SVX) and text (FTXT) and others. When the AGA Amigas appeared around 1992 then more file formats appeared for all sorts of files, it was advantageous for the Amiga to be able to read and write such formats, so a new shared library appeared in AmigaOS 3.0 for programs to read and write different file formats without having to re-write the wheel each time when new file formats appear, this is the Datatype library which can decode file formats easily using different classes which can be installed as they are needed.

Include the following headers to use datatypes:

#include <proto/datatypes.h>
#include <datatypes/datatypes.h>

To use datatypes, you need to open the datatypes library along with the other libraries in your program:

DataTypesBase = OpenLibrary ("datatypes.library", 39)
or, for AmigaOS 4:
DataTypesBase = IExec->OpenLibrary("datatypes.library", 50)

To create a Datatype Object, use the NewDTObject function as below:

Function:
Object o = NewDTObject(APTR name, Tag1[, tag2, tag3, ... ] )
Object o = NewDTObjectA(APTR name, struct TagItem *attrs)

For AmigaOS 4, prefix NewDTObject with 'IDataTypes->'.

The type of source that Datatypes can use include Clipboard (DTST_CLIPBOARD), a file (DTST_FILE),
RAM (DTST_RAM, DTST_MEMORY), or a hotlink (DTST_HOTLINK).

The group of objects you can use for Datatypes include:
GID_SYSTEM = System file, directory, program, library, device etc.
GID_TEXT = Text file.
GID_DOCUMENT = Formatted text with graphics etc.
GID_SOUND = Sounds.
GID_INSTRUMENT = Musical instruments.
GID_MUSIC = A musical score.
GID_PICTURE = A still picture.
GID_ANMIMATION = An animated picture
GID_MOVIE = Animation with audio track.

Example, read a object from the clipboard:

gd->gd_DisplayObject = NewDTObject ((APTR)gd->gd_Unit,
   DTA_SourceType, DTST_CLIPBOARD,
   GA_Immediate, TRUE,
   GA_RelVerify, TRUE,
   DTA_TextAttr, (ULONG) & gd->gd_TextAttr,
   TAG_DONE))
 

The parameters of this functions uses Tags as defined in datatypes/datatypesclasses.h and intuition/gadgetclass.h
gf->gd_Unit = the Clipboard unit number
DTST_Clipboard = the Clipboard is the data source
GA_Immediate = Should the object be active when displayed
GA_RelVerify = Verify that the pointer is over the object when it is selected
gd_->gd_TextAttr = Pointer to text font attributes

This example read a file to be displayed from 'pathname' and it is of type picture (ILBM, JPEG, GIF, PNG etc):

picDT = NewDTObject(pathname, DTA_SourceType, DTST_File, DTA_GroupID, GID_PICTURE,
   GA__Left, 10, GA_Top, 10, TAG_END); 

picDT = Object databastype created.
pathname = String containing path of the file to load.
DTST_FILE = Source is a file.
GID_Picture = Group of objects file must be long to i.e. Pictures.

Once we have a datatype loaded with NewDTObject, the program should create a window and then the datatype object
can be added to window or a requester, simply with single command:

Function:
LONG realposition = AddDTObject( struct Window *win, struct Requester *req, Object *obj, LONG pos);

Parameters:
win = Pointer to Window object (if not a Requester).
req = Pointer to an optional Requester object (if not a window)
obj = The Datatype object created with NewDTObject function.
pos = Position in gadget list. Use -1 to add it to end of the list.

Example,

realpos = AddDTObject(win, NULL, pictDT, -1);

Once a datatype object is no longer required, it is removed from the window and disposed of and memory released:

position = RemoveDTObject(window, object);

Function:
void DisposeDTObject(Object *o)
e.g.

RemoveDTObject(win, gd->gd_DisplayObject);

DisposeDTObject (gd->gd_DisplayObject);


For AmigaOS 4, prefix above functions with 'IDataTypes->'.

To get attributes from a datatype object, you can use the the GetDTAttrs function
e.g.

GetDTAttrs (gd->gd_DisplayObject, DTA_DataType, (ULONG)&dtn, TAG_DONE);
 

and examing the results from the dtn structure you can retreive:
dtn->dtn_Header->dth_Name = Descriptive name of the datatype.
dtn->dtn_Header->dth_GroupID = The group the datatype belongs to

The function GetDTString returns a localised Datatypes string of the id given. This string could be syst, text, docu,
soun, inst, musi, pict, anim or movi (see datatypes.h).
e.g.

GetDTString (dtn->dtn_Header->dth_GroupID) 

Other functions available for datatypes:
ObtainDataType(), ReleaseDataType(), SetDTAttrs(), RefreshDRObject(), DoAsyncLayout(), DoDTMethod(),
GetDTMethods(), DTMethods(), PrintDTObject().

More information about datatypes is available on AmigaOS Wiki.

Introduction to MUI