TABLE OF CONTENTS datatypes.library/--background-- datatypes.library/AddDTObject datatypes.library/CopyDTMethods datatypes.library/CopyDTTriggerMethods datatypes.library/DisposeDTObject datatypes.library/DoAsyncLayout datatypes.library/DoDTDomainA datatypes.library/DoDTMethodA datatypes.library/DrawDTObjectA datatypes.library/FindMethod datatypes.library/FindToolNodeA datatypes.library/FindTriggerMethod datatypes.library/FreeDTMethods datatypes.library/GetDTAttrsA datatypes.library/GetDTMethods datatypes.library/GetDTString datatypes.library/GetDTTriggerMethodDataFlags datatypes.library/GetDTTriggerMethods datatypes.library/LaunchToolA datatypes.library/LockDataType datatypes.library/NewDTObjectA datatypes.library/ObtainDataTypeA datatypes.library/ObtainDTDrawInfoA datatypes.library/PrintDTObjectA datatypes.library/RefreshDTObjectA datatypes.library/ReleaseDataType datatypes.library/ReleaseDTDrawInfo datatypes.library/RemoveDTObject datatypes.library/rexx/--rexxhost-- datatypes.library/rexx/EXAMINEDT datatypes.library/rexx/FINDTOOL datatypes.library/rexx/GETDTSTRING datatypes.library/rexx/LAUNCHTOOL datatypes.library/rexx/OBTAINDATATYPE datatypes.library/SaveDTObjectA datatypes.library/SetDTAttrsA datatypes.library/StartDragSelect datatypes.library/--background-- datatypes.library/--background-- PURPOSE The datatypes.library provides transparent data handling abilities to applications. Application developers can register their data format with datatypes.library and provide a class library for handling their data within other applications. OVERVIEW * Object Oriented datatypes.library implementation is object oriented, using the boopsi functions of Intuition. Each data class is implemented as a shared system library. * Embedded Objects datatypes.library provides the ability to embed different object types within an application. For example, an application can embed an picture object or even an AmigaGuide document browser within their application's window. Objects can also be embedded within other objects. * Gadget-like Embedded objects are actually boopsi gadgets. That means that input handling is done on Intuition's task. Time intensive operations, such as layout when the window size changes, are off-loaded to a sub-process. Printing, clipboard operations, file read/write are also off-loaded to a separate process on an as-needed basis. * Trigger Methods Sometimes it is necessary for an application to provide additional controls for navigating through an object. For example, with an AmigaGuide object it is necessary to have controls for "Contents", "Index", "Browse >", "Browse <". Each class implements a method that returns the trigger methods, and the appropriate labels, that a class supports. * Format Conversion As long as the objects are sub-classes of the same class, data from one format can be written out as another format. For example, it is possible to read in an ILBM file and write out a JPEG file, since both data types are sub-classes of PICTURE. * Future Compatible Each class implements a method that returns the supported methods within a class. This way an application can ask an object if it is capable of any particular method, such as DTM_WRITE for example. * Data Type Detection datatypes.library provides the ability to examine a file or the clipboard to determine what type of data it contains. datatypes.library/AddDTObject datatypes.library/AddDTObject NAME AddDTObject - Add an object to a window or requester. (V39) SYNOPSIS realposition = AddDTObject (window, requester, object, position); LONG AddDTObject (struct Window *, struct Requester *, Object *, LONG); FUNCTION This function adds a single object to the gadget list of the given window or requester at the position in the list specified by the position argument. When the object is added to the gadget list, the object will receive a GM_LAYOUT message with the gpl_Initial field set to one. If a requester is specified, this function will set the GTYP_REQGADGET flag (V45). INPUTS window - Pointer to the window. requester - Must be NULL. object - Pointer to an object as returned by NewDTObjectA(). position - Integer position in the list for the new gadget. -1 to add to the end of the list. RETURNS Returns the position of where the object was actually added. SEE ALSO RemoveDTObject(), intuition.library/AddGList() datatypes.library/CopyDTMethods datatypes.library/CopyDTMethods NAME CopyDTMethods -- Clone and modify DTA_Methods array (V45) SYNOPSIS newmethods = CopyDTMethods( methods, include, exclude ); ULONG *CopyDTMethods( ULONG *, ULONG *, ULONG * ); FUNCTION Copy and modify array of supported methods. This function is used for subclass implementors, who want to add their methods (like DTM_TRIGGER) to the array of supported methods. INPUTS methods - Methods array, as obtained by GetDTMethods or DTA_Methods. NULL causes the function to return NULL. include - Methods to include, ~0UL terminated. May be NULL. exclude - Methods to exclude, ~0UL terminated. May be NULL. RESULT newmethods - New array of methods or NULL (no memory). SEE ALSO FindMethod, CopyDTTriggerMethods, FreeDTMethods datatypes.library/CopyDTTriggerMethods datatypes.library/CopyDTTriggerMethods NAME CopyDTTriggerMethods -- Clone and modify DTA_TriggerMethods array (V45) SYNOPSIS newmethods = CopyDTTriggerMethods( methods, include, exclude ); struct DTMethod *CopyDTTriggerMethods( struct DTMethod *, struct DTMethod *, struct DTMethod * ); FUNCTION Copy and modify a DTMethods array. This function is for subclass implementors for an easy way to add their trigger methods to exising ones, or disable some because they're internally used. INPUTS methods - Methods array, as obtained by GetDTTriggerMethods or DTA_TriggerMethods. NULL causes the function to return NULL. include - Trigger methods to include. May be NULL. exclude - Trigger methods to exclude. May be NULL. The dtm_Command and dtm_Method fields may have the options described in FindTriggerMethod to filter/match out the given entries. NOTE It is assumed that the dtm_Label and dtm_Command strings are valid as long as the object exists. They are NOT copied. Subclasses which implements DTM_TRIGGER __MUST__ send unknown trigger methods to it's superclass. RESULT newmethods - New array of methods or NULL (no memory). SEE ALSO FindTriggerMethod, CopyDTMethods, FreeDTMethods datatypes.library/DisposeDTObject datatypes.library/DisposeDTObject NAME DisposeDTObject - Delete a data type object. (V39) SYNOPSIS DisposeDTObject (o); VOID DisposeDTObject (Object *); FUNCTION This function is used to dispose of a data type object that was obtained with NewDTObjectA(). INPUTS o - Pointer to an object as returned by NewDTObjectA(). NULL is a valid input. SEE ALSO NewDTObjectA() datatypes.library/DoAsyncLayout datatypes.library/DoAsyncLayout NAME DoAsyncLayout - Call the DTM_ASYNCLAYOUT method on a separate process . (V39) SYNOPSIS retval = DoAsyncLayout (object, gpl); ULONG DoAsyncLayout (Object *, struct gpLayout *); FUNCTION This function is used to asyncronously perform the object's DTM_ASYNCLAYOUT method. This is used to offload the layout method from input.device. The DTM_ASYNCLAYOUT method must exit when SIGBREAKF_CTRL_C signal is set. This indicates that the data has become obsolete and the DTM_ASYNCLAYOUT method will be called again. INPUTS object - Pointer to the data types object. gpl - Pointer to a gpLayout message. RETURNS SEE ALSO datatypes.library/DoDTDomainA datatypes.library/DoDTDomainA NAME DoDTDomainA -- Obtain the min/nom/max domains of a dt object (V45) SYNOPSIS retval = DoDTDomainA( o, win, req, rport, which, domain, attrs ); a0 a1 a2 a3 d0 a4 a5 ULONG DoDTDomainA( Object *, struct Window *, struct Requester *, struct RastPort *, ULONG, struct IBox *, struct TagItem * ); retval = DoDTDomain( o, win, req, rport, which, domain, tag1, ... ); ULONG DoDTDomain( Object *, struct Window *, struct Requester *, struct RastPort *, ULONG, struct IBox *, Tag, ... ); FUNCTION INPUTS o - Object like returned from NewDTObjectA win - Window the object is attached to req - Requester the object is attached to rport - RastPort, used for domain calculations which - one of the GDOMAIN_#? identifiers from domain - resulting domain box attrs - Additional attributes TAGS Subclass specific. Example: DTA_TextAttr (struct TextAttr *) - Default object font used for text calculations. RETURNS retval - The return value returned by GM_DOMAIN or 0UL for an error. domain - On success, the domain box will be filled with the gadget's domain dimensions for this particular GDOMAIN_#? id. EXAMPLE NOTE This function cannot handle the GM_DOMAIN method without an object. To do this, you have to use CoreceMethodA manually. SEE ALSO datatypesclass/GM_DOMAIN, datatypes.library/DoDTMethodA datatypes.library/DoDTMethodA NAME DoDTMethodA - Do a datatypes method. (V39) SYNOPSIS retval = DoDTMethodA (o, win, req, msg); ULONG DoDTMethodA (Object *, struct Window *, struct Requester *, Msg); retval = DoDTMethod (o, win, req, data, ...); ULONG DoDTMethod (Object *, struct Window *, struct Requester *, ULONG, ...); FUNCTION This function is used to perform a datatypes method. Please also read the function documentation of intuition.library/DoGadgetMethodA() and intuition.library/IDoMethodA(). WARNING: This function must not be used for methods whose structure does not contain a GadgetInfo field. An example of this is the PDTM_WRITEPIXELARRAY method of picture.datatype. INPUTS o - Pointer to an object as returned by NewDTObjectA(). win - Window that the object is attached to. req - Requester that the object is attached to. msg - The message to send to the object. RETURNS Returns the value returned by the method. SEE ALSO intuition.library/DoGadgetMethod() datatypes.library/DrawDTObjectA datatypes.library/DrawDTObjectA NAME DrawDTObjectA - Draw a DataTypes object. (V44) SYNOPSIS retval = DrawDTObjectA (rp, o, x, y, w, h, th, tv, attrs); LONG DrawDTObjectA (struct RastPort *rp, Object *, LONG x, LONG y, LONG w, LONG h, LONG th, LONG tv, struct TagItem *); retval = DrawDTObject (rp, o, x, y, w, h, th, tv, tag1, ...); LONG DrawDTObjectA (struct RastPort *rp, Object *, LONG x, LONG y, LONG w, LONG h, LONG th, LONG tv, Tag, ...); FUNCTION This function is used to draw a DataTypes object into a RastPort. This function can be used for strip printing the object or embedding it within a document. You must successfully call ObtainDTDrawInfoA() before using this function. This function invokes the object's DTM_DRAW method. Clipping MUST be turned on within the RastPort. This means that there must be a valid layer structure attached to the RastPort. INPUTS rp - Pointer to the RastPort to draw into. o - Pointer to an object returned by NewDTObjectA(). x - Left-most point of area to draw into. y - Top-most point of area to draw into. w - Width of area to draw into. h - Height of area to draw into. th - Horizontal top in units. tv - Vertical top in units. attrs - Additional attributes. TAGS none defined at this time. RETURNS TRUE to indicate that it was able to render, FALSE on failure. SEE ALSO ObtainDTDrawInfo(), ReleaseDTDrawInfo() datatypes.library/FindMethod datatypes.library/FindMethod NAME FindMethod -- find a specified method in methods array (V45) SYNOPSIS method = FindMethod( methods, searchmethodid ); ULONG *FindMethod( ULONG *, ULONG ); FUNCTION This function searches for a given method in a given methods array like got from GetDTMethods. INPUTS methods - methods array, like got from GetDTMethods or DTA_Methods NULL is a valid arg. searchmethodid - method id to find. RETURNS Pointer to the method table entry or NULL if not found. EXAMPLE /* This macro tests if a given method (like DTM_PRINT) is * supported by the given object */ #define IsDTMethodSupported( o, id ) \ ((BOOL)FindMethod(GetDTMethods( (o) ), (id) )) SEE ALSO GetDTMethods, CopyDTMethods datatypes.library/FindToolNodeA datatypes.library/FindToolNodeA NAME FindToolNodeA -- Find a tool node (V45) SYNOPSIS tn = FindToolNodeA( toollist, attrs ); d0 a0 a1 struct ToolNode *FindToolNodeA( struct List *, struct TagItem * ); tn = FindToolNode( toollist, tag1, ... ); ULONG FindToolNode( struct List *, ... ); FUNCTION This function searches for a given tool in a list of tool nodes. INPUTS toollist - struct List * or a struct ToolNode * (which will be skipped) to search in. NULL is a valid arg. attrs - Search tags. A NULL arg returns simple the following node. TAGS TOOLA_Program - name of the program to search for TOOLA_Which - one of the TW_#? types. TOOLA_LaunchType - Launch mode; TF_SHELL, TF_WORKBENCH or TF_RX RETURNS struct ToolNode * or NULL NOTE This function is not limited to the (&(DataType -> dtn_ToolList)); programmers can set up their own lists. The (&(DataType -> dtn_ToolList)) entries are valid as long as the application obtains a lock to the DataType (as obtained from a dt object, ObtainDataTypeA or LockDataType). SEE ALSO LaunchToolA datatypes.library/FindTriggerMethod datatypes.library/FindTriggerMethod NAME FindTriggerMethod -- find a specified trigger method in trigger methods array (V45) SYNOPSIS method = FindTriggerMethod( dtm, command, method ); struct DTMethod *FindTriggerMethod( struct DTMethod *, STRPTR, ULONG ); FUNCTION This function searches for a given trigger method in a given methods array like got from GetDTTriggerMethods. If one of the "command" or "method" args matches an array item, this function returns a pointer to it. INPUTS methods - trigger methods array, like got from GetDTTriggerMethods or DTA_TriggerMethods. NULL is a valid arg. command - trigger method command name (case-insensitive match), may be NULL (don't match). method - trigger method id, may be ~0UL (don't match). RETURNS Pointer to the trigger method table entry (struct DTMethod *) or NULL if not found. EXAMPLE SEE ALSO GetDTTriggerMethods, CopyDTTriggerMethods datatypes.library/FreeDTMethods datatypes.library/FreeDTMethods NAME FreeDTMethods -- Free methods array obtained by CopyDT#?Methods (V45) SYNOPSIS FreeDTMethods( methods ); VOID FreeDTMethods( APTR ); FUNCTION INPUTS methods - Methods array, as obtained by CopyDTMethods or CopyDTTriggerMethods. NULL is a valid input. SEE ALSO CopyDTMethods, CopyDTTriggerMethods datatypes.library/GetDTAttrsA datatypes.library/GetDTAttrsA NAME GetDTAttrsA - Obtain attributes for an object. (V39) SYNOPSIS retval = GetDTAttrsA (o, attrs); ULONG GetDTAttrsA (Object *, struct TagItem *); retval = GetDTAttrs (o, tag1, ...); ULONG GetDTAttrs (Object *, Tag tag1, ...); FUNCTION This function is used to get the attributes of a data type object. INPUTS o - Pointer to an object as returned by NewDTObjectA(). attrs - Attributes to get, terminated with TAG_DONE. The data element of each pair contains the address of the storage variable. RETURNS retval - Contains the number of attributes the system was able to obtain. SEE ALSO SetDTAttrsA(), intuition.library/GetAttr() datatypes.library/GetDTMethods datatypes.library/GetDTMethods NAME GetDTMethods - Obtain methods an object supports. (V39) SYNOPSIS methods = GetDTMethods (object); ULONG GetDTMethods (Object *); FUNCTION This function is used to obtain a list of methods that an object supports. INPUTS object - Pointer to an object as returned by NewDTObjectA(). NULL is a valid arg (V45). RETURNS Returns a pointer to a ~0 terminated ULONG array. This array is only valid until the object is disposed off. SEE ALSO GetDTTriggerMethods() datatypes.library/GetDTString datatypes.library/GetDTString NAME GetDTString - Obtain a DataTypes string. (V39) SYNOPSIS str = GetDTString (id); CONST_STRPTR GetDTString (ULONG id); FUNCTION This function is used to obtain a pointer to a localized DataTypes string. INPUTS id - ID of the string to obtain. RETURNS A pointer to a NUL-terminated read-only string. WARNING The language of the strings returned by this function may be different than the current system default language. The charset of the strings returned by this function may be different than the current system default charset and different from the charset of the GUI of your application (which should be identical to the charset of the catalog which contains your localized GUI strings). You should better open Sys/libs.catalog with OpenCatalog() (specify OC_WantedCharset when you already opened another catalog with your GUI strings to get the same charset) and use GetCatalogString() instead of GetDTString(). SEE ALSO datatypes.library/GetDTTriggerMethodDataFlagsrary/GetDTTriggerMethodDataFlags NAME GetDTTriggerMethodDataFlags -- Get data type of dtt_Data value (V45) SYNOPSIS type = GetDTTriggerMethodDataFlags( method ); d0 ULONG GetDTTriggerMethodDataFlags( ULONG ); FUNCTION This function returns the kind of data which can be attached to the stt_Data field in the dtTrigger method body. The data type can be specified by or'ing the method id (within STMF_METHOD_MASK value) with one of the STMD_#? identifiers: STMD_VOID - stt_Data MUST be NULL STMD_ULONG - stt_Data contains an unsigned long value STMD_STRPTR - stt_Data is a string pointer STMD_TAGLIST - stt_Data points to an array of struct TagItem's, terminated with TAG_DONE The trigger methods below STM_USER are explicitly handled, as described in , e.g. STM_COMMAND return STMD_STRPTR, instead of STMD_VOID. INPUTS method - dtt_Method ID from struct DTMethod RESULT type - one of the STMD_#? identifies in EXAMPLE struct DTMethod htmldtc_dtm[] = { "Stop Loading", "STOP", (STM_STOP | STMD_VOID), "Load Images", "LOADIMAGES", ((STM_USER + 20) | STMD_VOID), "Goto URL", "GOTOURL", ((STM_USER + 21) | STMD_STRPTR), NULL, NULL, 0L }; Sets up three methods: "STOP" takes no arguments, "LOADIMAGES" takes no arguments and "GOTOURL" takes a STRPTR as an argument. SEE ALSO CopyDTTriggerMethods, FindTriggerMethod, datatypesclass/DTM_TRIGGER datatypes.library/GetDTTriggerMethods datatypes.library/GetDTTriggerMethods NAME GetDTTriggerMethods - Obtain trigger methods supported by an object (V39) SYNOPSIS methods = GetDTTriggerMethods (object); struct DTMethod *GetDTTriggerMethods (Object *); FUNCTION This function is used to obtain a list of trigger methods that an object supports. This is so that an application can provide the appropriate controls for an object. For example, an AmigaGuide object needs controls for "Contents", "Index", "Retrace", "Browse <", and "Browse >", INPUTS object - Pointer to an object as returned by NewDTObjectA(). RETURNS Returns a pointer to a NULL terminated DTMethod list. This list is only valid until the object is disposed off. EXAMPLE To call the method: DoMethod (object, DTM_TRIGGER, dtm[button]->dtm_Method); SEE ALSO GetDTMethods() datatypes.library/LaunchToolA datatypes.library/LaunchToolA NAME LaunchToolA -- invoke a given tool with project (V45) SYNOPSIS success = LaunchToolA( tool, project, attrs ); d0 a0 a1 a2 ULONG LaunchToolA( struct Tool *, STRPTR, struct TagItem * ); success = LaunchTool( tool, project, tag1, ... ); ULONG LaunchTool( struct Tool *, STRPTR, ... ); FUNCTION This function launches an application with a specified project. The application and it's launch mode and other attributes are specified through the "Tool" structure. INPUTS tool - Pointer to a Tool structure. NULL is a valid arg. project - Name of the project to execute or NULL. attrs - Additional attributes. TAGS NP_Priority (BYTE) - sets the priority of the launched tool Defaults to the current process's priority for Shell and ARexx programs; Workbench applications defaults to 0 except overridden by the TOOLPRI tooltype. NP_Synchronous (BOOL) - don't return until lauched application process finishes. Defaults to FALSE. Also see 'NOTE' below. Other tags are __currently__ ignored. RETURNS FALSE for failure, non-zero for success. EXAMPLE NOTE - This function requires the "RX" command when lauching ARexx scripts. - This function must be launched from a process, not a simple task. - This function is not limited to use the struct DataType->dtn_Tools tools. Applications can set up their own struct Tool's as long as these structures contains no rubbish. If you don't know the TW_#? ("which") type of your custom tool, set tn_Which to TW_MISC. - The NP_Synchronous tag has been removed from in v51 because dos.library never supported this feature. In v51.8+ of datatypes.library SYS_Asynch can be used instead. BUGS - The path of the launched tools depends on the parents path. If there is no path, shell tools can only launch other tools with their full path. SEE ALSO FindToolNodeA datatypes.library/LockDataType datatypes.library/LockDataType NAME LockDataType -- Lock a DataType structure. (V45) SYNOPSIS LockDataType( dtn ); a0 VOID LockDataType( struct DataType * ); FUNCTION This function is used to lock a DataType structure obtained by ObtainDataTypeA or a datatypes object (DTA_DataType attribute). All calls to LockDataType or ObtainDataTypeA must match the same number of ReleaseDataType calls, otherwise havoc will break out. INPUTS dtn - DataType structure returned by ObtainDataTypeA. NULL is a valid input. NOTE This function has been made public to allow to get a DataType structure from an object (DTA_DataType attribute), and remain the reference valid after the object has been disposed off (which unlocks the DataType structure locked in NewDTObjectA). SEE ALSO ObtainDataTypeA, ReleaseDataType datatypes.library/NewDTObjectA datatypes.library/NewDTObjectA NAME NewDTObjectA - Create an data type object. (V39) SYNOPSIS o = NewDTObjectA (name, attrs); Object *NewDTObjectA (STRPTR, struct TagItem *); o = NewDTObject (name, tag1, ...); Object *NewDTObject (STRPTR, Tag tag1, ...); FUNCTION This is the method for creating datatype objects from 'boopsi' classes. Boopsi' stands for "basic object-oriented programming system for Intuition".) You further specify initial "create-time" attributes for the object via a TagItem list, and they are applied to the resulting datatype object that is returned. INPUTS name - Name of the data source. Usually an existing file name. attrs - Pointer to a taglist containing additional arguments. TAGS DTA_SourceType - Specify the type of source data; such as coming from a file or clipboard (defaults to DTST_FILE). If source type is clipboard, then the name field contains the numeric clipboard unit. If source type is DTST_MEMORY, the name field will be ignored (V44). DTA_Handle - Can optionally be used instead of the name field. Must be a valid FileHandle if DTA_SourceType is DTST_FILE. Must be a valid IFFHandle if DTA_SourceType is DTST_CLIPBOARD. Will be ignored if DTA_SourceType is DTST_MEMORY. DTA_DataType - Specify the class of data. Data is a pointer to a valid DataType. This is only used when attempting to create a new object that doesn't have any source data. DTA_GroupID - Specify that the object must be of this type, or NewDTObject() will fail with IoErr() of ERROR_OBJECT_WRONG_TYPE. DTA_SourceAddress (APTR) -- For DTST_MEMORY source data, this specifies the memory address at which the source data is located. This must be non-NULL. This attribute is required for DTST_MEMORY source data (V44). DTA_SourceSize (ULONG) -- For DTST_MEMORY source data, this specifies the size of the source data (in bytes). This must be greater than 0. This attribute is required for DTST_MEMORY source data (V44). DTA_BaseName (STRPTR) -- Specify base name of datatype to use. This tag should be used rarely (e.g. if a matching descriptor does not exists). It must only be used with DTST_RAM. When passing both DTA_BaseName and DTA_DataType, DTA_BaseName will be ignored (V45). DTA_Class (struct IClass *) -- Specify the class to create an object from. Useful when creating private subclasses inside applications (e.g. when a subclass is needed to superset some methods. New for V45.3). GA_Left, GA_RelRight, GA_Top, GA_RelBottom, GA_Width, GA_RelWidth, GA_Height, GA_RelHeight - Specify the placement of the object within the destination window. GA_ID - Specify the object ID. GA_UserData - Specify the application specific data for the object. RETURNS A boopsi object, which may be used in different contexts such as a gadget or image, and may be manipulated by generic functions. You eventually free the object using DisposeDTObject(). A NULL return indicates failure. Use IoErr() to get error value. Following is a summary of the error number used and there meaning as it relates to DataTypes. ERROR_REQUIRED_ARG_MISSING - Indicates that a required attribute wasn't passed in. ERROR_BAD_NUMBER - An invalid group ID was passed in. ERROR_OBJECT_WRONG_TYPE - Object data type doesn't match DTA_GroupID. ERROR_NO_FREE_STORE - Not enough memory. DTERROR_UNKNOWN_DATATYPE - Unable to open the class library associated with the data type. DTERROR_COULDNT_OPEN - Unable to open the data object. ERROR_NOT_IMPLEMENTED - Unknown handle type. NOTES This function invokes the OM_NEW "method" for the class specified. The DTST_MEMORY source type introduced in V44 makes in-memory data available to subclasses as if the data were stored in a file. Thus, subclasses will see the data as DTST_FILE. Since the data does not correspond to an on-disk file, subclasses and examine hook code must not assume that they will be able to reopen the "file" whose data has been provided to them. EXAMPLE STRPTR fileName = "s:startup-sequence" Object *o; /* Simplest use is to just open an existing file */ if (o = NewDTObject ((APTR)fileName, NULL)) { /* Free the object when we are done with it */ DisposeDTObject (o); } SEE ALSO AddDTObject(), DisposeDTObject(), RemoveDTObject(), intuition.library/NewObjectA() datatypes.library/ObtainDataTypeA datatypes.library/ObtainDataTypeA NAME ObtainDataTypeA - Examines a handle and return its DataType. (V39) SYNOPSIS dtn = ObtainDataTypeA (type, handle, attrs); struct DataType *ObtainDataTypeA (ULONG, APTR, struct TagItem *); dtn = ObtainDataType (type, handle, tag1, ...); struct DataType *ObtainDataType (ULONG, APTR, Tag tag1, ...); FUNCTION This function examines the data that the handle points to, and returns a DataType record that describes the data. INPUTS type - Type of handle. handle - Handle to examine. For DTST_FILE, handle must be BPTR lock. For DTST_CLIPBOARD, handle must be struct IFFHandle *. For DTST_MEMORY, handle will be ignored (you need to specify the additional information required by this source type through the attrs list). For DTST_RAM (V45), handle must be a STRPTR (DataType name, equals to the dtn_Name field) or NULL. attrs - Additional attributes (see TAGS). TAGS DTA_SourceAddress (APTR) -- For DTST_MEMORY source data, this specifies the memory address at which the source data is located. This must be non-NULL. This attribute is required for DTST_MEMORY source data (V44). DTA_SourceSize (ULONG) -- For DTST_MEMORY source data, this specifies the size of the source data (in bytes). This must be greater than 0. This attribute is required for DTST_MEMORY source data (V44). DTA_GroupID (ULONG) -- GID_#? group to match 0 is a valid input and means all groups (V45). In V45 only DTST_RAM supported this attribute, this has been changed in V52.2 (post 4.0 final release ). DTA_DataType (struct DataType *) -- Search in descriptor list starts at this point (maybe result of a previous datatype). The given datatype will NOT be unlocked. NULL is a valid input (start at the begin of list). DTST_RAM source data only (V45). NOTES The datatypes.library maintains a sorted list of all the DataType descriptors. The descriptor can consist of a function, a data mask for the first 64 bytes of the data, and a name pattern. The sort order for the list is: Descriptors with a function and no mask or name pattern. Descriptors with a function and a mask or name pattern. Descriptors with no function and a mask or name pattern. Within each group, they are also sorted in descending priority and descending mask length. The DTST_MEMORY source type introduced in V44 makes in-memory data available to subclasses as if the data were stored in a file. Thus, subclasses will see the data as DTST_FILE. Since the data does not correspond to an on-disk file, subclasses and examine hook code must not assume that they will be able to reopen the "file" whose data has been provided to them. RETURNS Success returns a pointer to a DataType. You must call ReleaseDataType() when you are done with the handle. A NULL return indicates failure. Use IoErr() to get error value. Following is a summary of the error number used and there meaning as it relates to DataTypes. ERROR_NO_FREE_STORE - Not enough memory. ERROR_OBJECT_NOT_FOUND - Unable to open the data object. ERROR_NOT_IMPLEMENTED - Unknown handle type. EXAMPLE The following code can be used to list all available datatypes: struct DataType *dt, *prevdt = NULL; while ((dt = ObtainDataType(DTST_RAM,NULL, DTA_DataType, prevdt, TAG_DONE)) != NULL) { ReleaseDataType(prevdt); prevdt = dt; Printf("%s\n", dt->dtn_Name); } ReleaseDataType(prevdt); SEE ALSO ReleaseDataType() datatypes.library/ObtainDTDrawInfoA datatypes.library/ObtainDTDrawInfoA NAME ObtainDTDrawInfoA - Obtain a DataTypes object for drawing. (V44) SYNOPSIS handle = ObtainDTDrawInfoA (o, attrs); APTR ObtainDTDrawInfoA (Object *, struct TagItem *); handle = ObtainDTDrawInfo (o, tag1, ...); APTR ObtainDTDrawInfo (Object *, Tag, ...); FUNCTION This function is used to prepare a DataTypes object for drawing into a RastPort. This function will send the DTM_OBTAINDRAWINFO method to the object using the opSet message structure. INPUTS o - Pointer to an object as returned by NewDTObjectA(). attrs - Additional attributes. RETURNS Returns a opaque handle that must be passed to ReleaseDTDrawInfo() when the application is done drawing the object. NOTE This function implies a layout operation. Thus, you must not add the object in question to a window or requester and use ObtainDTDrawInfo() on it. TAGS none defined at this time. SEE ALSO DrawDTObjectA(), ReleaseDTDrawInfo() datatypes.library/PrintDTObjectA datatypes.library/PrintDTObjectA NAME PrintDTObjectA - Call the DTM_PRINT method on a separate process. (V39) SYNOPSIS retval = PrintDTObjectA (object, window, requester, msg); ULONG PrintDTObjectA (Object *, struct Window *, struct Requester *, struct dtPrint *); retval = PrintDTObject (object, window, requester, data, ...); ULONG PrintDTObject (Object *, struct Window *, struct Requester *, ULONG, ...); FUNCTION This function is used to asyncronously perform the object's DTM_PRINT method. Once the application has performed the PrintDTObjectA() function, it must not manipulate the printerIO union until it receives a IDCMP_IDCMPUPDATE message that contains the DTA_PrinterStatus tag. To abort a print, the application sends the DTM_ABORTPRINT method to the object. This in turn signals the print process with a SIGBREAKF_CTRL_C. INPUTS object - Pointer to the DataTypes object. window - Pointer to the window that the object has been added to. requester - Pointer to the requester that the object has been added to. RETURNS Returns TRUE if successful, FALSE on error. SEE ALSO datatypes.library/RefreshDTObjectA datatypes.library/RefreshDTObjectA NAME RefreshDTObjectA - Refresh a datatypes object. (V39) SYNOPSIS RefreshDTObjectA (object, window, req, attrs) VOID RefreshDTObjectA (Object *, struct Window *, struct Requester *, struct TagItem *); RefreshDTObject (object, window, req, tag1, ...); VOID RefreshDTObject (Object *, struct Window *, struct Requester *, Tag tag1, ...); FUNCTION Refreshes the specified object, by sending the GM_RENDER method to the object. INPUTS object - Pointer to an object as returned by NewDTObjectA(). window - Pointer to the window. req - Requester that the object is attached to (V45). attrs - Additional attributes (currently none are defined). SEE ALSO AddDTObject(), RemoveDTObject(), intuition.library/RefreshGList() datatypes.library/ReleaseDataType datatypes.library/ReleaseDataType NAME ReleaseDataType - Release a DataType structure. (V39) SYNOPSIS ReleaseDataType (dtn); VOID ReleaseDataType (struct DataType *); FUNCTION This function is used to release a DataType structure obtained by ObtainDataTypeA(). INPUTS dtn - DataType structure returned by ObtainDataTypeA(). NULL is a valid input. SEE ALSO ObtainDataTypeA() datatypes.library/ReleaseDTDrawInfo datatypes.library/ReleaseDTDrawInfo NAME ReleaseDTDrawInfo - Release a DataTypes object from drawing. (V44) SYNOPSIS ReleaseDTDrawInfo (o, handle); VOID ReleaseDTDrawInfo (Object *, APTR); FUNCTION This function is used to release the information obtained with ObtainDTDrawInfoA(). This function invokes the object's DTM_RELEASEDRAWINFO method using the opMember message structure. INPUTS handle - Pointer to an object returned by ObtainDTDrawInfoA(). SEE ALSO DrawDTObjectA(), ObtainDTDrawInfo() datatypes.library/RemoveDTObject datatypes.library/RemoveDTObject NAME RemoveDTObject - Remove an object from a window. (V39) SYNOPSIS position = RemoveDTObject (window, object); LONG RemoveDTObject (struct Window *, Object *); FUNCTION Removes the object from the window's object list. This will wait until the AsyncLayout process is complete. The object will receive a DTM_REMOVEDTOBJECT message to inform the object it has been removed. Starting V45 the GTYP_REQGADGET flag is cleared. INPUTS window - Pointer to the window. object - Pointer to an object as returned by NewDTObjectA(). RETURNS Returns the ordinal position of the removed object. If the object wasn't found in the appropriate list then a -1 is returned. SEE ALSO AddDTObject(), intuition.library/RemoveGList() datatypes.library/rexx/--rexxhost-- datatypes.library/rexx/--rexxhost-- HOST INTERFACE datatypes.library provides an ARexx function host interface that enables ARexx programs to take advantage of the features of data types. The functions provided by the interface are directly related to the functions described herein, with the differences mostly being in the way they are called. The function host library vector is located at offset -30 from the library. This is the value you provide to ARexx in the AddLib() function call. FUNCTIONS OBTAINDATATYPE - Obtain datatype from a given file, clipboard or by other specs FINDTTOOL - Find a tool by name, type etc. LAUNCHTOOL - Launch a tool OBTAINDTSTRING - Obtain datatypes string EXAMINEDT - Examine a given file datatypes.library/rexx/EXAMINEDT datatypes.library/rexx/EXAMINEDT NAME EXAMINEDT -- Examine given file SYNOPSIS EXAMINEDT( FILENAME/A, STEM, STORAGE ) FUNCTION EXAMINEDT obtains data type and other attributes of the given filesystem object. INPUTS FILENAME - filesystem object (file/dir/etc.) to examine STEM - Name of stem variable to store data in STORAGE - Type of result storage, one of "STEM" or "VAR" RESULTS If STORAGE was set to "VAR", the result is the datatype name. On error, the numeric DOS error code is returned. If STORAGE was set to "STEM" (and a stem var was given), the stem var has the following members: DISKKEY Filesystem disk key DIRENTRYTYPE Dir Entry Type, one of 1 root directory (for UNIX fs) 2 directory 3 soft link (looks like dir, but may point to a file !) 4 hard link to directory -3 file -4 hard link to file -5 pipe file FILENAME File Name PROTECTION Protection OTHERPROTECTION Other Protection GROUPPROTECTION Group Protection ENTRYTYPE Entry Type, see DIRENTRYTYPE for types SIZE Size of file in bytes NUMBLOCKS Blocks DATE Date (AmigaDOS style) COMMENT Comment OWNERUID Owner User ID OWNERGID Owner Group ID OWNERUIDNAME Owner User Name OWNERGIDNAME Owner Group Name BASETYPE Type, one of "binary", "ascii", "iff" or "other" BASETYPENAME Localized form of BASETYPE DATATYPE File Type BASENAME Base Name GROUPID DataTypes GroupID, like "syst", "text", "docu", ... GROUPIDNAME Localized format of GROUPID, like "System", "Text", "Document", ... The function result contains the error code, (0 on success, 1 - 2099 otherwise). EXAMPLE /* examinedt.rexx */ PARSE ARG fname OPTIONS RESULTS /* Load the datatypes.library as a function host */ IF ~SHOW( 'L', 'datatypes.library' ) THEN CALL ADDLIB( 'datatypes.library', 0, -30 ) IF fname="" THEN DO SAY "Usage:" SAY " rx examinedt " EXIT END SAY 'var test' type = ExamineDT( fname,,VAR ) SAY type SAY 'stem test' CALL ExamineDT( fname, dtstem., STEM ) SAY ' Disk Key:' dtstem.DiskKey SAY ' Dir Entry Type:' dtstem.DirEntryType SAY ' File Name:' dtstem.FileName SAY ' Protection:' dtstem.Protection SAY ' Other Protection:' dtstem.OtherProtection SAY ' Group Protection:' dtstem.GroupProtection SAY ' Entry Type:' dtstem.EntryType SAY ' Size:' dtstem.Size SAY ' Blocks:' dtstem.NumBlocks SAY ' Date:' dtstem.Date SAY ' Comment:' dtstem.Comment SAY ' Owner User ID:' dtstem.OwnerUID SAY ' Owner Group ID:' dtstem.OwnerGID SAY ' Type:' dtstem.BaseType SAY ' File Type:' dtstem.DataType SAY ' Base Name:' dtstem.BaseName SAY ' DT GroupID:' dtstem.GroupID EXIT NOTE - Owner User Name and Owner Group Name requires fs support for ACTION_UID2UNAME and ACTION_GID2GNAME (like envoy fs). - Error handling has been changed in V45. On error, the function now returns the error number (1 - 2099), which can be converted using rexx/GETDTSTRING; only serious errors (like "no memory") will end in a rexx error code. SEE ALSO rexx/OBTAINDATATYPE datatypes.library/rexx/FINDTOOL datatypes.library/rexx/FINDTOOL NAME FINDTOOL -- Find a single tool stem from given pattern SYNOPSIS FINDTOOL( TOOLLISTSTEM/A, START/N, PROGRAM, WHICH, LAUNCHTYPE ) FUNCTION Find a single tool stem within a TOOLLIST stem as returned by OBTAINDATATYPE INPUTS TOOLLISTSTEM -- a stem variable with TOOL stems and a TOOLLIST.COUNT var. START - Start index, beginning from 0. Note that the given index will be skipped, and the search starts at the following node. Defaults to -1 (e.g. next node is 0). WHICH - Type of application One of "misc", "info", "browse", "edit", "print", "mail". Defaults to "", which means: Match all Which-Types LAUNCH - Launch mode, one of "shell", "workbench", "rx" Defaults to "", which means: Match all Launch-modes PROGRAM - Full path of the program to be launched RETURNS The index of the toolstem found or -1. EXAMPLE NOTE SEE ALSO rexx/OBTAINDATATYPE datatypes.library/rexx/GETDTSTRING datatypes.library/rexx/GETDTSTRING NAME GETDTSTRING -- Get (localized) datatypes string SYNOPSIS GETDTSTRING( ID/A, NAME ) FUNCTION Gets a (localized) datatypes string and returns it in RESULT. INPUTS ID -- string number, like DTERROR_#? from include:datatypes/datatypes.h 2000 - "Unknown data type for %s" and so on... or one of "syst#?", "docu#?", ... or one of "binary", "ascii", "iff", "other" (or "Miscellaneous") Error codes from 1-499 belongs to DOS, error codes from 500-999 belongs to ENVOY and error codes from 2000-2099 belongs to DataTypes. Codes between 2100 and 2999 are used to access localizes DataTypes strings. NAME -- Name be be inserted into the string RETURNS string EXAMPLE NOTE - Does not support the envoy error code space. SEE ALSO datatypes.library/rexx/LAUNCHTOOL datatypes.library/rexx/LAUNCHTOOL NAME LAUNCHTOOL -- Lauch a tool from given spec SYNOPSIS LAUNCHTOOL( TOOLSTEM/A, PROJECT, SYNCHRONOUS=SYNC/S, PRIORITY/N ) FUNCTION Lauch a tool with an argument (e.g. project file). As set by the TOOL stem, the tool may be lauched from Shell, from Workbench or from ARexx. INPUTS TOOLSTEM -- a stem variable with following members (this stem var is normally set up by OBTAINDATATYPE (TOOLLIST stem)): WHICH - Type of application One of "misc", "info", "browse", "edit", "print", "mail". If you don't know the "which"-type of your tool, set this to "misc". LAUNCH - Launch mode, one of "shell", "workbench", "rx" PROGRAM - Full path of the program to be launched PROJECT -- Name of the project file to be used (passed as an argument to the application). SYNCHRONOUS SYNC -- Wait for child exit ? If set, LaunchTool waits until the invoked program quits. PRIORITY -- Set task priority of the lauched application. RETURNS Success (0) or failure (>0) EXAMPLE NOTE SEE ALSO rexx/OBTAINDATATYPE datatypes.library/rexx/OBTAINDATATYPE datatypes.library/rexx/OBTAINDATATYPE NAME OBTAINDATATYPE -- Obtain datatype from given handle SYNOPSIS OBTAINDATATYPE( TYPE/A, HANDLE/A, STEM/A, DATATYPE, GID ) FUNCTION Obtain datatype from given handle. INPUTS TYPE -- Type of HANDLE data One of "RAM", "CLIPBOARD", "FILE" or "HOTLINK" HANDLE -- Handle type. For TYPE = "RAM", this is the DataType name to be searched for. An empty string is treated as an NULL arg. For TYPE = "CLIPBOARD", this is the numeric clipboard unit. For TYPE = "FILE", this is the full path of a file/dir to be examined. TYPE = "HOTLINK" is not implemented yet. STEM -- Name of the result stem var DATATYPE -- Name of the datatype to start at. Used when scanning the descriptor list. GID -- Group ID filter, one of "System", "Text", "Document", "Sound", "Instrument", "Music", "Picture", "Animation", "Movie". If set, only descriptors of this type will be returned. RETURNS Success (0) or failure (> 0) The given stem var has the following members: HEADER.NAME - Name of the descriptor HEADER.BASENAME - Base name (class library name) HEADER.PATTERN - File pattern HEADER.GROUPID - Group ID, one of "syst", "text", "docu", "soun", "inst", "musi", "pict", "anim", "movi" HEADER.GROUPIDNAME - Localized format of HEADER.GROUPID, (e.g. "System", "Text", ... HEADER.ID - For IFF datatypes, this is the IFF FORM code, for other datatypes these are the first four letters of the name field HEADER.ID - For IFF datatypes, this is the IFF FORM code, for other datatypes these are the first four letters of the name field HEADER.BASETYPE - Base type, on of "binary", "ascii", "iff", "other" HEADER.BASETYPENAME - Localized format of HEADER.BASETYPE (e.g. "Binary", "ASCII", "IFF", "Miscellaneous" FUNCTIONNAME - Name of comparisation function TOOLLIST. - Tool nodes stem list, with following members TOOLLIST.COUNT - Total number of tool nodes in this list TOOLLIST.i.WHICH - "Which" sort of program, one of "misc", "info", "browse", "edit", "print", "mail", "undefined" TOOLLIST.i.LAUNCH - Launch mode of tool, one of "shell", "workbench", "rx", "undefined" TOOLLIST.i.PROGRAM - Full path of the tool TOOLLIST.i.FLAGS - Hex-Version of toolnodes "flags" field, usage should be rare... 'i' above means loop-"interator". EXAMPLE PARSE ARG fname OPTIONS RESULTS /* Load the datatypes.library as a function host */ IF ~SHOW( 'L', 'datatypes.library' ) THEN CALL ADDLIB( 'datatypes.library', 0, -30 ) IF fname="" THEN DO SAY "Usage:" SAY " rx obtaindatatype " EXIT END SAY 'stem test' CALL ObtainDataType( FILE, fname, dtstem. ) SAY ' Name:' dtstem.header.name SAY ' Basename:' dtstem.header.basename SAY ' Pattern:' dtstem.header.pattern SAY ' GroupID:' dtstem.header.groupid SAY ' ID:' dtstem.header.id SAY ' Basetype:' dtstem.header.basetype SAY ' Functionname:' dtstem.functionname DO i = 0 TO (dtstem.toollist.count - 1) SAY 'Tool Node ' i SAY ' Program:' dtstem.toollist.i.program SAY ' Which:' dtstem.toollist.i.which SAY ' Launch:' dtstem.toollist.i.launch SAY ' Flags:' dtstem.toollist.i.flags END EXIT NOTE SEE ALSO rexx/EXAMINEDT, rexx/LAUNCHTOOL datatypes.library/SaveDTObjectA datatypes.library/SaveDTObjectA NAME SaveDTObjectA -- Save object's contents (V45) SYNOPSIS success = SaveDTObjectA( o, win, req, file, mode, saveicon, attrs ); ULONG SaveDTObjectA( Object *, struct Window *, struct Requester *, STRPTR, ULONG, BOOL, struct TagItem * ); success = SaveDTObject( o, win, req, file, mode, saveicon, tag1, ... ); ULONG SaveDTObject( Object *, struct Window *, struct Requester *, STRPTR, ULONG, BOOL, Tag, ... ); FUNCTION This function saves the contents of an object into a file. The function opens the named file and saves the object's contexts into it (DTM_WRITE). Then it closes the file. If the DTM_WRITE method returns success and the saveicon option is TRUE, matching icon is saved. If DTM_WRITE returns 0, the file will be deleted. INPUTS o - Object like returned from NewDTObjectA win - Window the object is attached to req - Requester the object is attached to file - file name to save to mode - Save mode, (RAW, IFF etc.), one of the DTWM_#? identifiers saveicon - Save icon? Does not overwrite an existing icon. attrs - Additional attributs TAGS Subclass specific. For example, animation.datatype V41 recognizes ADTA_Frame (start frame to save) and ADTA_Frames (number of frames to save). RETURNS success - The return value returned by DTM_WRITE or NULL for an error. BUGS SEE ALSO datatypesclass/DTM_WRITE datatypes.library/SetDTAttrsA datatypes.library/SetDTAttrsA NAME SetDTAttrsA - Set attributes for an object. (V39) SYNOPSIS retval = SetDTAttrsA (o, win, req, attrs); ULONG SetDTAttrsA (Object *, struct Window *, struct Requester *, struct TagItem *); retval = SetDTAttrs (o, win, req, tag1, ...); ULONG SetDTAttrs (Object *, struct Window *, struct Requester *, Tag tag1, ...); FUNCTION This function is used to set the attributes of a data type object. INPUTS o - Pointer to an object as returned by NewDTObjectA(). win - Window that the object has been added to. attrs - Attributes to set, terminated with TAG_DONE. TAGS see for tags. SEE ALSO GetDTAttrsA(), intuition.library/SetGadgetAttrsA() datatypes.library/StartDragSelect datatypes.library/StartDragSelect NAME StartDragSelect -- Start drag-selection (V45) SYNOPSIS success = StartDragSelect( o ); ULONG StartDragSelect( Object * ); FUNCTION This function starts drag-selection by the user (marking). This function replaces the old flag-fiddling method to start drag-select. The drag-select will only be started of the object supports DTM_SELECT, is in a window or requester and no layout-process is working on the object. If all conditions are good, it sets the DTSIF_DRAGSELECT flag and returns TRUE for success. INPUTS o - object like returned from NewDTObjectA RETURNS TRUE for success, FALSE for failure SEE ALSO