home *** CD-ROM | disk | FTP | other *** search
/ telefisk.org / virusCollection.lzx / VirusResearch / DataType-trojan / arcs / dtypes454upd.lha / datatypes.library.doc next >
Encoding:
Text File  |  1997-11-13  |  106.9 KB  |  3,243 lines
  1. TABLE OF CONTENTS
  2.  
  3. datatypes.library/--background--
  4. datatypes.library/--history--
  5. datatypes.library/--V45_release--
  6. datatypes.library/AddDTObject
  7. datatypes.library/CopyDTMethods
  8. datatypes.library/CopyDTTriggerMethods
  9. datatypes.library/DisposeDTObject
  10. datatypes.library/DoAsyncLayout
  11. datatypes.library/DoDTDomainA
  12. datatypes.library/DoDTMethodA
  13. datatypes.library/DrawDTObjectA
  14. datatypes.library/FindMethod
  15. datatypes.library/FindToolNodeA
  16. datatypes.library/FindTriggerMethod
  17. datatypes.library/FreeDTMethods
  18. datatypes.library/GetDTAttrsA
  19. datatypes.library/GetDTMethods
  20. datatypes.library/GetDTString
  21. datatypes.library/GetDTTriggerMethodDataFlags
  22. datatypes.library/GetDTTriggerMethods
  23. datatypes.library/LaunchToolA
  24. datatypes.library/LockDataType
  25. datatypes.library/NewDTObjectA
  26. datatypes.library/ObtainDataTypeA
  27. datatypes.library/ObtainDTDrawInfoA
  28. datatypes.library/PrintDTObjectA
  29. datatypes.library/RefreshDTObjectA
  30. datatypes.library/ReleaseDataType
  31. datatypes.library/ReleaseDTDrawInfo
  32. datatypes.library/RemoveDTObject
  33. datatypes.library/rexx/--rexxhost--
  34. datatypes.library/rexx/EXAMINEDT
  35. datatypes.library/rexx/FINDTOOL
  36. datatypes.library/rexx/GETDTSTRING
  37. datatypes.library/rexx/LAUNCHTOOL
  38. datatypes.library/rexx/OBTAINDATATYPE
  39. datatypes.library/SaveDTObjectA
  40. datatypes.library/SetDTAttrsA
  41. datatypes.library/StartDragSelect
  42. datatypesclass/--datasheed--
  43. datatypesclass/DTM_ABORTPRINT
  44. datatypesclass/DTM_ASYNCLAYOUT
  45. datatypesclass/DTM_FRAMEBOX
  46. datatypesclass/DTM_PRINT
  47. datatypesclass/DTM_PROCLAYOUT
  48. datatypesclass/DTM_REMOVEDTOBJECT
  49. datatypesclass/DTM_WRITE
  50. datatypesclass/GM_DOMAIN
  51. datatypesclass/GM_GOACTIVE
  52. datatypesclass/GM_GOINACTIVE
  53. datatypesclass/GM_HANDLEINPUT
  54. datatypesclass/GM_HITTEST
  55. datatypesclass/GM_LAYOUT
  56. datatypesclass/OM_DISPOSE
  57. datatypesclass/OM_GET
  58. datatypesclass/OM_NEW
  59. datatypesclass/OM_SET
  60. datatypesclass/OM_UPDATE
  61. datatypes.library/--background--             datatypes.library/--background--
  62.  
  63.     PURPOSE
  64.         The datatypes.library provides transparent data handling
  65.         abilities to applications.  Application developers can register
  66.         their data format with datatypes.library and provide a class
  67.         library for handling their data within other applications.
  68.  
  69.     OVERVIEW
  70.  
  71.         * Object Oriented
  72.  
  73.           datatypes.library implementation is object oriented, using the
  74.           boopsi functions of Intuition.  Each data class is implemented
  75.           as a shared system library.
  76.  
  77.         * Embedded Objects
  78.  
  79.           datatypes.library provides the ability to embed different object
  80.           types within an application.  For example, an application can
  81.           embed an picture object or even an AmigaGuide document browser
  82.           within their application's window.  Objects can also be embedded
  83.           within other objects.
  84.  
  85.           See Examples/embed_datatype/
  86.  
  87.         * Gadget-like
  88.  
  89.           Embedded objects are actually boopsi gadgets.  That means that
  90.           input handling is done on Intuition's task.  Time intensive
  91.           operations, such as layout when the window size changes, are
  92.           off-loaded to a sub-process.  Printing, clipboard operations,
  93.           file read/write are also off-loaded to a separate process on an
  94.           as-needed basis.
  95.  
  96.           See Examples/DTRequester/DTRequester.c
  97.  
  98.         * Image-like
  99.  
  100.           Embedded objects can also be treated as boopsi images.
  101.           For example, an application can draw an image into the background
  102.           of it's GUI, without fiddling with any internals of the object.
  103.  
  104.           See Examples/DTImage/DTImage.c
  105.  
  106.         * Trigger Methods
  107.  
  108.           Sometimes it is necessary for an application to provide
  109.           additional controls for navigating through an object.  For
  110.           example, with an AmigaGuide object it is necessary to have
  111.           controls for "Contents", "Index", "Browse >", "Browse <".  Each
  112.           class implements a method that returns the trigger methods, and
  113.           the appropriate labels, that a class supports. Options can
  114.           also provided to those trigger methods.
  115.  
  116.           See Examples/DTRequester/DTRequester.c
  117.  
  118.         * Format Conversion
  119.  
  120.           As long as the objects are sub-classes of the same class, data
  121.           from one format can be written out as another format.  For
  122.           example, it is possible to read in an ILBM file and write out a
  123.           JPEG file, since both data types are sub-classes of PICTURE.
  124.  
  125.           See Examples/DTConvert/DTConvert.c
  126.  
  127.         * Future Compatible
  128.  
  129.           Each class implements a method that returns the supported
  130.           methods within a class.  This way an application can ask an
  131.           object if it is capable of any particular method, such as
  132.           DTM_WRITE for example.
  133.  
  134.         * Data Type Detection
  135.  
  136.           datatypes.library provides the ability to examine a file or
  137.           the clipboard to determine what type of data it contains.
  138.  
  139.           See Examples/DoDT/DoDT.c and
  140.               Examples/DTDescrlist/DTDescrlist.c
  141.  
  142.         * "Supported Tools"
  143.  
  144.           datatypes.library maintains lists (for each data type) of
  145.           applications which supports this special datatype for their
  146.           actions (browse, edit, info, print, mail etc.).
  147.           These tools can be launched from within datatypes.library.
  148.  
  149.           This lists can be edited using AddDataTypes (AddDataTypes edit).
  150.  
  151.           See Examples/DoDT/DoDT.c and
  152.               Examples/DTDescrlist/DTDescrlist.c
  153.  
  154.  
  155. datatypes.library/--history--                   datatypes.library/--history--
  156.  
  157.     V45.4
  158.         - Recompiled with SAS/C 6.58.
  159.           This may fix mc68060 related problems (I was searching for this
  160.           mc68060 incompatibility a long time :-((       ).
  161.  
  162.         - Fixed a bug in LaunchToolA that the given strings were not
  163.           freed on some conditions.
  164.           Fixed.
  165.  
  166.         - Fixed a bug (race condition) in RemoveDTObject that
  167.           DTM_REMOVEDTOBJECT was executed BEFORE internal RemoveGadget.
  168.           Now DTM_REMOVEDTOBJECT is correctly executed AFTER RemoveGadget.
  169.  
  170.         - Internal Delay's (when waiting for flags in RemoveDTObject and
  171.           DisposeDTObject etc.)
  172.           have been reduced from 1/2 sec down to 1/5 sec.
  173.  
  174.         - StartDragSelect now sets Result2 (IoErr()) with valid return
  175.           codes.
  176.  
  177.         - All library calls to datatypes.library are now going througth
  178.           the LVO explicitly.
  179.  
  180.         - ObtainDataTypeA has been rewritten to get more speed.
  181.           This fixes also some bugs, see below.
  182.  
  183.         - ObtainDataTypeA: Fixed the bug that a 0 in the comparisation mask
  184.           was treated as an empty mask field.
  185.           Now the 0 is correctly recognized.
  186.           This fixes the bug with the QRT descriptor and some other formats.
  187.           Fixed.
  188.  
  189.         - ObtainDataTypeA: Endless loop in conjunction with "PostScript"
  190.           descriptors and "DTDescrList". Problem was that the code to get
  191.           the next node from a given node didn't expect that two nodes
  192.           have the same name.
  193.           Fixed.
  194.  
  195.         - ObtainDataTypeA: Fixed the memory loss of n * 40 bytes (e.g.
  196.           loss of a iffparse.library IFFHandle).
  197.           Thanks to Oliver Robers (oliver@poboxes.com) for reporting the bug.
  198.           Fixed.
  199.  
  200.         - ObtainDataTypeA: Fixed a bug that an custom compatisation hook
  201.           (e.g. the DTCD code in a descriptor) for IFF forats gets an
  202.           IFFHandle and a file handle. Now only the IFFHandle is given, the
  203.           file handle is NULL (because iffparse.library manages the file
  204.           handle).
  205.           Fixed.
  206.  
  207.         - ObtainDataTypeA: The clipboard did not work with masks longer
  208.           than 64 bytes.
  209.           Fixed.
  210.  
  211.         - Increased the stack size of the async layout process from 8192
  212.           up to 16384 bytes. Should be __really__ enougth now.
  213.  
  214.         - Changed the behaviour of DoAsyncLayout:
  215.           Previously, the DTSIF_LAYOUT flag was used to indicate that a
  216.           layout process is running.
  217.           Now the DTA_LayoutProc attribute is always checked.
  218.           The "normal" Forbid / Permit protection of async layout process
  219.           creation / signalling / deletion has been replaced by an 
  220.           internal datatypes.library semaphore.
  221.  
  222.         - Increased the stack size of the printer process. Should be
  223.          __really__ enougth now.
  224.  
  225.  
  226. datatypes.library/--V45_release--           datatypes.library/--V45_release--
  227.  
  228.     MISC
  229.         The datatypes.library V45 has been written to replace the old
  230.         datatypes.library V40.6
  231.  
  232.         It introduces some interesting new features, fixes some
  233.         inconsistensies and sets more strictly rules when using
  234.         objects.
  235.  
  236.     FEATURES
  237.         - The new datatypes.library V45 supports "tools", which are attached
  238.           to each datatype. Those user-defined tools are defined to handle
  239.           the datatype, an application which uses datatypes is now able to
  240.           select such a tool, search for it and launch it.
  241.  
  242.         - DataTypes objects can reside inside a intuition requester.
  243.  
  244.         - Supports GM_DOMAIN, which allows to include a datatypes object
  245.           in environments which uses dynamic layout (like MUI, for example).
  246.  
  247.         - Implements and describes DTM_OBTAINDRAWINFO/DTM_DRAW/
  248.           DTM_RELEASEDRAWINFO, which allows usage of a datatypes object as
  249.           an image.
  250.  
  251.         - V45 defines an interface for progressive loading (like GIF
  252.           pictures or SGML/HTML texts).
  253.  
  254.         - Added some usefull interfaces, such as SaveDTObjectA (DTM_WRITE)
  255.           or StartDragSelect (marking).
  256.  
  257.     RULES
  258.         The following list has not been completet yet...
  259.  
  260.         The new datatypes.library is fully backwards compatible to V40.6,
  261.         but adds new features, and will rely on them if a datatype class
  262.         has a version equal or higher than V45.
  263.  
  264.         - All subclasses must use a ClassLibrary structure.
  265.  
  266.           from <intuition/classes.h>, V40.0
  267.  
  268.           -- snip --
  269.  
  270.             struct ClassLibrary
  271.             {
  272.               struct Library  cl_Lib;   /* Embedded library     */
  273.               UWORD           cl_Pad;   /* Align the structure  */
  274.               Class          *cl_Class; /* Class pointer        */
  275.             };
  276.  
  277.           -- snip --
  278.  
  279.           This was intruduced to support GM_DOMAIN and other methods
  280.           which does not require an object, and to be consistent
  281.           with other boopsi classes which should have also this interface.
  282.  
  283.         - All subclasses have to support requesters. I've included
  284.           a small example which explains the usage, see
  285.           "Examples/dtrequester/dtrequester.c".
  286.           Currently, only picture.datatype V42.1, sound.datatype
  287.           and animation.datatype V41 supports this correctly.
  288.  
  289.         - A DTM_WRITE method with a NULL file handle must be a NOP, but
  290.           returning correct return codes in Resul2 (IoErr).
  291.           This was introduced to check if a particular subclass supports
  292.           DTM_WRITE with DTWM_RAW (local format).
  293.  
  294.         - V45 introduces an "Application" and a "Subclass" interface.
  295.           This means that the applicability of attributes for applications
  296.           and subclasses are different.
  297.           For example, the DTA_ObjName is (ISGU) for subclasses, and
  298.           (G) for applications.
  299.           (The only exception of this is if an application creates an object
  300.           with DTST_RAM. This application will be allowed to act like a
  301.           subclass).
  302.  
  303.         - Objects must be able to be added to a window as a gadget
  304.           (AddDTObject), beeing removed from it (RemoveDTObject), added again
  305.           an another window in another screen. This must be repeatable
  306.           in any number (see Examples/Examples/DTRequester.c, '+' and '-'
  307.           keyboard shortcuts).
  308.  
  309.         - If a datatypes class is not designed to support sub-classes, the
  310.           OM_NEW method MUST reject such an attempt (ERROR_NOT_IMPLEMENTED).
  311.  
  312.           The following statement handels such a case:
  313.  
  314.           /* This must not be a subclass of embed.datatype
  315.            * (not implemented nor supported)
  316.            */
  317.           if( o == (Object *)cl )
  318.           {
  319.             /* Ok ! */
  320.           }
  321.           else
  322.           {
  323.             /* Subclasses of embed.datatype are not supported */
  324.             SetIoErr( ERROR_NOT_IMPLEMENTED );
  325.           }
  326.  
  327.         - Check your inputs. Maybe, an application tries to feed a datatype
  328.           object with rubbish.
  329.  
  330.           A common mistake the datatype classes have today is the missing
  331.           check if the datatype supports the given input handle type (e.g.
  332.           the DTA_SourceType attribute).
  333.  
  334.           The following code shows the correct check for this (checked
  335.           inside OM_NEW):
  336.  
  337.           -- snip --
  338.  
  339.           /* We only support DTST_FILE as source type */
  340.           if( ti = FindTagItem( DTA_SourceType,
  341.                                 (((struct opSet *)msg) -> ops_AttrList) ) )
  342.           {
  343.             if( (ti -> ti_Data) != DTST_FILE )
  344.             {
  345.               SetIoErr( ERROR_NOT_IMPLEMENTED );
  346.  
  347.               break;
  348.             }
  349.           }
  350.  
  351.           -- snip --
  352.  
  353.           Note: The DTA_SourceType attribute is examined from the OM_NEW
  354.           msg (ops_AttrList). You __MUST__ not examine DTA_Handle in such a
  355.           way.
  356.           The DTA_Handle is set up by datatypesclass ONLY, and noone else.
  357.           See OM_GET/DTA_Handle for further explanations.
  358.  
  359.         - Each datatype should be shipped with an autodoc, which contains
  360.           (at least) the following entries:
  361.  
  362.           --datatsheed--    Short summary of the datatype
  363.           --input_format--  Description how the input format looks like
  364.           OM_NEW            What attributes does the datatype recognize ?
  365.           OM_SET/OM_UPDATE  Attributes to set/update etc.
  366.  
  367.           and so on.
  368.  
  369.     TODO
  370.         - Add a general, flexible preferences scheme.
  371.  
  372. datatypes.library/AddDTObject                   datatypes.library/AddDTObject
  373.  
  374.      NAME
  375.         AddDTObject -- Add an object to a window or requester.   (V39)
  376.  
  377.      SYNOPSIS
  378.         realposition = AddDTObject( window, requester, object, position );
  379.         d0                          a0      a1         a2      d0
  380.  
  381.         LONG AddDTObject( struct Window *, struct Requester *,
  382.                           Object *, LONG );
  383.  
  384.      FUNCTION
  385.         This function adds a single object to the gadget list of the given
  386.         window or requester at the position in the list specified by the
  387.         position argument.
  388.  
  389.         When the object is added to the gadget list, the object will
  390.         receive a GM_LAYOUT message with the gpl_Initial field set to
  391.         one.
  392.  
  393.         If a requester is specified, this function will set the 
  394.         GTYP_REQGADGET flag.
  395.  
  396.      INPUTS
  397.         window    - Pointer to the window.
  398.                     A NULL arg is NOP (V45).
  399.  
  400.         requester - Pointer to the requester (V45)
  401.  
  402.         object    - Pointer to an object as returned by NewDTObjectA.
  403.                     A NULL arg is NOP (V45).
  404.  
  405.         position  - Integer position in the list for the new gadget.
  406.                     -1 to add to the end of the list.
  407.  
  408.      RETURNS
  409.         Returns the position of where the object was actually added.
  410.  
  411.      NOTE
  412.         Since V45, DataTypes objects can be added to requesters, too.
  413.         But you can only rely on this feature if the datatype itself
  414.         has the version V45. A requester in which a datatype resides
  415.         must not be closed before the datatype got a DTM_REMOVEDTOBJECT msg,
  416.         must not be a DM Requester nor have a GACT_ENGADGET gadget.
  417.  
  418.         Note that this function __MUST__ not be uses when a datatype
  419.         object is embedded within another BOOPSI gadget. The
  420.         parent object is responsible to pass all required methods
  421.         including initial GM_LAYOUT and DTM_REMOVEDTOBJECT to
  422.         the embedded object.
  423.  
  424.      BUGS
  425.         If a requester was specified, GM_LAYOUT is send manually
  426.         by this function (intuition.library didn't send a GM_LAYOUT,
  427.         OS bug ??).
  428.  
  429.      SEE ALSO
  430.         RemoveDTObject,
  431.         intuition.library/AddGList
  432.  
  433. datatypes.library/CopyDTMethods               datatypes.library/CopyDTMethods
  434.  
  435.    NAME
  436.         CopyDTMethods -- Clone and modify DTA_Methods array (V45)
  437.  
  438.    SYNOPSIS
  439.         newmethods = CopyDTMethods( methods, include, exclude );
  440.                                     a0       a1       a2
  441.  
  442.         ULONG *CopyDTMethods( ULONG *, ULONG *, ULONG * );
  443.  
  444.    FUNCTION
  445.         Copy and modify array of supported methods.
  446.  
  447.         This function is used for subclass implementors, who want to
  448.         add their methods (like DTM_TRIGGER) to the array of supported
  449.         methods.
  450.  
  451.    INPUTS
  452.         methods - Methods array, as obtained by GetDTMethods or DTA_Methods.
  453.             NULL causes the function to return NULL.
  454.  
  455.         include - Methods to include, ~0UL terminated. May be NULL.
  456.  
  457.         exclude - Methods to exclude, ~0UL terminated. May be NULL.
  458.  
  459.    RESULT
  460.         newmethods - New array of methods or NULL (no memory).
  461.  
  462.    BUGS
  463.         Methods to exclude will simply be overwritten by OM_NEW.
  464.         This is not really a bug, since OM_NEW should appear in any
  465.         DTA_Methods array.
  466.  
  467.    SEE ALSO
  468.         FindMethod,
  469.         CopyDTTriggerMethods,
  470.         FreeDTMethods
  471.  
  472. datatypes.library/CopyDTTriggerMethods datatypes.library/CopyDTTriggerMethods
  473.  
  474.    NAME
  475.         CopyDTTriggerMethods -- Clone and modify DTA_TriggerMethods array
  476.                                                                       (V45)
  477.  
  478.    SYNOPSIS
  479.         newmethods = CopyDTTriggerMethods( methods, include, exclude );
  480.                                            a0       a1       a2
  481.  
  482.         struct DTMethod *CopyDTTriggerMethods( struct DTMethod *,
  483.                                                struct DTMethod *,
  484.                                                struct DTMethod * );
  485.  
  486.    FUNCTION
  487.         Copy and modify a DTMethods array.
  488.         This function is for subclass implementors for an easy way to
  489.         add their trigger methods to exising ones, or disable some because
  490.         they're internally used.
  491.  
  492.    INPUTS
  493.         methods - Methods array, as obtained by GetDTTriggerMethods or
  494.             DTA_TriggerMethods.
  495.             NULL causes the function to return NULL.
  496.  
  497.         include - Trigger methods to include. May be NULL.
  498.  
  499.         exclude - Trigger methods to exclude. May be NULL.
  500.                   The dtm_Command and dtm_Method fields may have
  501.                   the options described in FindTriggerMethod to
  502.                   filter/match out the given entries.
  503.  
  504.    NOTE
  505.         It is assumed that the dtm_Label and dtm_Command strings are
  506.         valid as long as the object exists. They are NOT copied.
  507.  
  508.         Subclasses which implements DTM_TRIGGER __MUST__ send unknown
  509.         trigger methods to it's superclass.
  510.  
  511.    RESULT
  512.         newmethods - New array of methods or NULL (no memory).
  513.  
  514.    SEE ALSO
  515.         FindTriggerMethod,
  516.         CopyDTMethods,
  517.         FreeDTMethods
  518.  
  519. datatypes.library/DisposeDTObject           datatypes.library/DisposeDTObject
  520.  
  521.      NAME
  522.         DisposeDTObject -- Delete a data type object.            (V39)
  523.  
  524.      SYNOPSIS
  525.         DisposeDTObject( o );
  526.                          a0
  527.  
  528.         VOID DisposeDTObject( Object * );
  529.  
  530.      FUNCTION
  531.         This function is used to dispose of a data type object that was
  532.         obtained with NewDTObjectA. The shared class library which
  533.         was opened at NewDTObjectA time will also be closed.
  534.  
  535.         This function will wait for an outstanding print or layout process.
  536.  
  537.      INPUTS
  538.         o - Pointer to an object as returned by NewDTObjectA.
  539.             NULL is a valid input.
  540.  
  541.      NOTE
  542.         Be sure that the boopsi class struct IClass member cl_UserData points
  543.         to the shared library class base.
  544.  
  545.      SEE ALSO
  546.         NewDTObjectA,
  547.         intuition.library/DisposeObject,
  548.         datatypesclass/OM_DISPOSE
  549.  
  550. datatypes.library/DoAsyncLayout               datatypes.library/DoAsyncLayout
  551.  
  552.      NAME
  553.         DoAsyncLayout -- Call the DTM_ASYNCLAYOUT method on a separate
  554.                          process.                                     (V39)
  555.  
  556.      SYNOPSIS
  557.         retval = DoAsyncLayout( object, gpl );
  558.         d0                      a0      a1
  559.  
  560.         ULONG DoAsyncLayout( Object *, struct gpLayout * );
  561.  
  562.      FUNCTION
  563.         This function is used to asyncronously perform the object's
  564.         DTM_ASYNCLAYOUT method.  This is used to offload the layout method
  565.         from input.device.
  566.  
  567.         The DTM_ASYNCLAYOUT method must exit when SIGBREAKF_CTRL_C signal
  568.         is set.   This indicates that the data has become obsolete and
  569.         the DTM_ASYNCLAYOUT method will be called again.
  570.  
  571.         Starting with V45, the stack size increases from 4096 up to 8192
  572.         bytes.
  573.  
  574.      INPUTS
  575.         object - Pointer to the data types object.
  576.  
  577.         gpl    - Pointer to a gpLayout message.
  578.  
  579.      RETURNS
  580.         TRUE for success, FALSE for failure
  581.  
  582.      NOTE
  583.         - Note that the "AsyncDTLayoutDaemon" process obtains the
  584.           DTSpecialInfo semaphore exclusively before triggering the
  585.           DTM_ASYNCLAYOUT method. It will be released immediately when the
  586.           method is done.
  587.  
  588.         - When a layout deamon process is started, this function send a
  589.           notify msg with { DTA_Data, NULL }. This msg indicates
  590.           that there are currently no data available in this object.
  591.  
  592.           When DTM_ASYNCLAYOUT is done, the layout deamon sends a notify msg
  593.           with the following tags:
  594.  
  595.           { GA_ID,               Gadget ID             },
  596.           { DTA_Data,            object                },
  597.           { DTA_TopVert,         (dtsi -> si_TopVert)  },
  598.           { DTA_VisibleVert,     (dtsi -> si_VisVert)  },
  599.           { DTA_TotalVert,       (dtsi -> si_TotVert)  },
  600.           { DTA_TopHoriz,        (dtsi -> si_TopHoriz) },
  601.           { DTA_VisibleHoriz,    (dtsi -> si_VisHoriz) },
  602.           { DTA_TotalHoriz,      (dtsi -> si_TotHoriz) },
  603.           { DTA_Sync,            TRUE                  },
  604.           { DTA_Busy,            FALSE                 }
  605.  
  606.      SEE ALSO
  607.         datatypesclass/DTM_ASYNCLAYOUT
  608.  
  609. datatypes.library/DoDTDomainA                   datatypes.library/DoDTDomainA
  610.  
  611.    NAME
  612.         DoDTDomainA -- Obtain the min/nom/max domains of a dt object (V45)
  613.  
  614.    SYNOPSIS
  615.         retval = DoDTDomainA( o, win, req, rport, which, domain, attrs );
  616.                               a0 a1   a2   a3     d0     a4      a5
  617.  
  618.         ULONG DoDTDomainA( Object *, struct Window *, struct Requester *,
  619.               struct RastPort *, ULONG, struct IBox *, struct TagItem * );
  620.  
  621.         retval = DoDTDomain( o, win, req, rport, which, domain, tag1,
  622.                              ... );
  623.  
  624.         ULONG DoDTDomain( Object *, struct Window *, struct Requester *,
  625.               struct RastPort *, ULONG, struct IBox *, Tag, ... );
  626.  
  627.    FUNCTION
  628.  
  629.    INPUTS
  630.         o      - Object like returned from NewDTObjectA
  631.  
  632.         win    - Window the object is attached to
  633.  
  634.         req    - Requester the object is attached to
  635.  
  636.         rport  - RastPort, used for domain calculations
  637.  
  638.         which  - one of the GDOMAIN_#? identifiers from
  639.             <intuition/gadgetclass.h>
  640.  
  641.         domain - resulting domain box
  642.  
  643.         attrs  - Additional attributes
  644.  
  645.    TAGS
  646.         Subclass specific.
  647.  
  648.         Example:
  649.             DTA_TextAttr (struct TextAttr *) - Default object font
  650.                 used for text calculations.
  651.  
  652.    RETURNS
  653.         retval - The return value returned by GM_DOMAIN or 0UL for an error.
  654.  
  655.         domain - On success, the domain box will be filled with the
  656.                  gadget's domain dimensions for this particular GDOMAIN_#?
  657.                  id.
  658.  
  659.    EXAMPLE
  660.         See "Examples/dtrequester/dtrequester.c" or
  661.         "Examples/dtimage/dtimage.c".
  662.  
  663.    NOTE
  664.         This function cannot handle the GM_DOMAIN method without
  665.         an object. To do this, you have to use CoreceMethodA
  666.         manually.
  667.  
  668.    SEE ALSO
  669.         datatypesclass/GM_DOMAIN,
  670.         <intuition/gadgetclass.h>
  671.  
  672. datatypes.library/DoDTMethodA                   datatypes.library/DoDTMethodA
  673.  
  674.      NAME
  675.         DoDTMethodA -- Do a datatypes method.                    (V39)
  676.  
  677.      SYNOPSIS
  678.         retval = DoDTMethodA( o, win, req, msg );
  679.         d0                    a0 a1   a2   a3
  680.  
  681.         ULONG DoDTMethodA( Object *, struct Window *, struct Requester *,
  682.                            Msg );
  683.  
  684.         retval = DoDTMethod( o, win, req, data, ... );
  685.  
  686.         ULONG DoDTMethod( Object *, struct Window *, struct Requester *,
  687.                           ULONG, ... );
  688.  
  689.      FUNCTION
  690.         This function is used to perform a method on a datatypes object.
  691.  
  692.      INPUTS
  693.         o   - Pointer to an object as returned by NewDTObjectA.
  694.  
  695.         win - Pointer to a window that the object is attached to.
  696.  
  697.         req - Pointer to a requester that the object is attached to. (V45)
  698.  
  699.         msg - The message to send to the object.
  700.  
  701.      RETURNS
  702.         retval - Returns the value returned by the method.
  703.  
  704.      SEE ALSO
  705.         intuition.library/DoGadgetMethodA
  706.  
  707. datatypes.library/DrawDTObjectA               datatypes.library/DrawDTObjectA
  708.  
  709.    NAME
  710.        DrawDTObjectA -- Draw a DataTypes object.                (V39)
  711.  
  712.    SYNOPSIS
  713.        retval = DrawDTObjectA( rp, o, x, y, w, h, th, tv, attrs );
  714.        d0                      a0  a1 d0 d1 d2 d3 d4  d5  a2
  715.  
  716.        LONG DrawDTObjectA( struct RastPort *, Object *, LONG, LONG,
  717.                            LONG, LONG, LONG, LONG,
  718.                            struct TagItem * );
  719.  
  720.        retval = DrawDTObject( rp, o, x, y, w, h, th, tv, tag1, ... );
  721.  
  722.        LONG DrawDTObject( struct RastPort *, Object *, LONG, LONG,
  723.                           LONG, LONG, LONG, LONG, Tag, ... );
  724.  
  725.    FUNCTION
  726.        This function is used to draw a DataTypes object into a RastPort.
  727.  
  728.        This function can be used for strip printing the object or
  729.        embedding it within a document.
  730.  
  731.        You must successfully call ObtainDTDrawInfoA before using
  732.        this function.
  733.  
  734.        This function invokes the object's DTM_DRAW method.
  735.  
  736.        Clipping MUST be turned on within the RastPort.  This means
  737.        that there must be a valid layer structure attached to the
  738.        RastPort, otherwise some datatypes can't draw (FALSE returned).
  739.  
  740.    INPUTS
  741.        rp    - Pointer to the RastPort to draw into.
  742.                Starting with V45, a NULL arg will result in a NOP.
  743.  
  744.        o     - Pointer to an object returned by NewDTObjectA.
  745.                Starting with V45, a NULL arg will result in a NOP.
  746.  
  747.        x     - Left edge of area to draw into.
  748.  
  749.        y     - Top edge of area to draw into.
  750.  
  751.        w     - Width of area to draw into.
  752.  
  753.        h     - Height of area to draw into.
  754.  
  755.        th    - Horizontal top in units.
  756.  
  757.        tv    - Vertical top in units.
  758.  
  759.        attrs - Additional attributes.
  760.  
  761.    TAGS
  762.        Good args args are ADTA_Frame for animationclass objects (requires
  763.        animationclass V41), which selects the frame beeing drawn.
  764.  
  765.    RETURNS
  766.        TRUE to indicate that it was able to render, FALSE on failure;
  767.  
  768.    EXAMPLES
  769.        See "Examples/dtimage/dtimage.c".
  770.  
  771.    SEE ALSO
  772.        ObtainDTDrawInfo, ReleaseDTDrawInfo,
  773.        intuition.library/DrawImageState,
  774.        "Examples/dtimage/dtimage.c".
  775.  
  776. datatypes.library/FindMethod                     datatypes.library/FindMethod
  777.  
  778.    NAME
  779.         FindMethod -- find a specified method in methods array (V45)
  780.  
  781.    SYNOPSIS
  782.         method = FindMethod( methods, searchmethodid );
  783.         d0                   a0       a1
  784.  
  785.         ULONG *FindMethod( ULONG *, ULONG );
  786.  
  787.    FUNCTION
  788.         This function searches for a given method in a given methods
  789.         array like got from GetDTMethods.
  790.  
  791.    INPUTS
  792.         methods - methods array, like got from GetDTMethods or DTA_Methods
  793.                   NULL is a valid arg.
  794.  
  795.         searchmethodid - method id to find.
  796.  
  797.    RETURNS
  798.         Pointer to the method table entry or NULL if not found.
  799.  
  800.    EXAMPLE
  801.         /* This macro tests if a given method (like DTM_PRINT) is
  802.          * supported by the given object
  803.          */
  804.         #define IsDTMethodSupported( o, id ) \
  805.                 ((BOOL)FindMethod(GetDTMethods( (o) ), (id) ))
  806.  
  807.    SEE ALSO
  808.        GetDTMethods,
  809.        CopyDTMethods
  810.  
  811. datatypes.library/FindToolNodeA               datatypes.library/FindToolNodeA
  812.  
  813.    NAME
  814.         FindToolNodeA -- Find a tool node (V45)
  815.  
  816.    SYNOPSIS
  817.         tn = FindToolNodeA( toollist, attrs );
  818.         d0                  a0        a1
  819.  
  820.         struct ToolNode *FindToolNodeA( struct List *,
  821.                                         struct TagItem * );
  822.  
  823.         tn = FindToolNode( toollist, tag1, ... );
  824.  
  825.         ULONG FindToolNode( struct List *, ... );
  826.  
  827.    FUNCTION
  828.         This function searches for a given tool in a list of tool nodes.
  829.  
  830.    INPUTS
  831.         toollist - struct List * or a struct ToolNode * (which will be
  832.                    skipped) to search in.
  833.                    NULL is a valid arg.
  834.  
  835.         attrs    - Search tags.
  836.                    A NULL arg returns simple the following node.
  837.  
  838.    TAGS
  839.         TOOLA_Program    - name of the program to search for
  840.  
  841.         TOOLA_Which      - one of the TW_#? types.
  842.  
  843.         TOOLA_LaunchType - Launch mode; TF_SHELL, TF_WORKBENCH or TF_RX
  844.  
  845.    RETURNS
  846.         struct ToolNode * or NULL
  847.  
  848.    EXAMPLE
  849.         See "Examples/DoDT/DoDT.c".
  850.  
  851.    NOTE
  852.         This function is not limitted to the (&(DataType -> dtn_ToolList));
  853.         programmers can set up their own lists.
  854.         The (&(DataType -> dtn_ToolList)) entries are valid as long as 
  855.         the application obtains a lock to the DataType (as obtained from
  856.         a dt object, ObtainDataTypeA or LockDataType).
  857.  
  858.    SEE ALSO
  859.        LaunchToolA
  860.  
  861. datatypes.library/FindTriggerMethod       datatypes.library/FindTriggerMethod
  862.  
  863.    NAME
  864.         FindTriggerMethod -- find a specified trigger method in trigger
  865.                              methods array                         (V45)
  866.  
  867.    SYNOPSIS
  868.         method = FindTriggerMethod( dtm, command, method );
  869.         d0                          a0   a1       d0
  870.  
  871.         struct DTMethod *FindTriggerMethod( struct DTMethod *, STRPTR, 
  872.                                             ULONG );
  873.  
  874.    FUNCTION
  875.         This function searches for a given trigger method in a given methods
  876.         array like got from GetDTTriggerMethods.
  877.  
  878.         If one of the "command" or "method" args matches a array item, this
  879.         function returns a pointer to it.
  880.  
  881.    INPUTS
  882.         methods - trigger methods array, like got from GetDTTriggerMethods
  883.                   or DTA_TriggerMethods.
  884.                   NULL is a valid arg.
  885.  
  886.         command - trigger method command name (case-insensitive match),
  887.                   may be NULL (don't match).
  888.  
  889.         method  - trigger method id,
  890.                   may be ~0UL (don't match).
  891.  
  892.    RETURNS
  893.         Pointer to the trigger method table entry (struct DTMethod *) or
  894.         NULL if not found.
  895.  
  896.    EXAMPLE
  897.  
  898.    SEE ALSO
  899.        GetDTTriggerMethods,
  900.        CopyDTTriggerMethods
  901.  
  902. datatypes.library/FreeDTMethods               datatypes.library/FreeDTMethods
  903.  
  904.    NAME
  905.         FreeDTMethods -- Free methods array obtained by CopyDT#?Methods (V45)
  906.  
  907.    SYNOPSIS
  908.         FreeDTMethods( methods );
  909.                        a0
  910.  
  911.         VOID FreeDTMethods( APTR );
  912.  
  913.    FUNCTION
  914.  
  915.    INPUTS
  916.         methods - Methods array, as obtained by CopyDTMethods or
  917.             CopyDTTriggerMethods. NULL is a valid input.
  918.  
  919.    SEE ALSO
  920.         CopyDTMethods,
  921.         CopyDTTriggerMethods
  922.  
  923. datatypes.library/GetDTAttrsA                   datatypes.library/GetDTAttrsA
  924.  
  925.      NAME
  926.         GetDTAttrsA -- Obtain attributes for an object.          (V39)
  927.  
  928.      SYNOPSIS
  929.         retval = GetDTAttrsA( o, attrs );
  930.         d0                    a0 a2
  931.  
  932.         ULONG GetDTAttrsA( Object *, struct TagItem * );
  933.  
  934.         retval = GetDTAttrs( o, tag1, ... );
  935.  
  936.         ULONG GetDTAttrs( Object *, Tag, ... );
  937.  
  938.      FUNCTION
  939.         This function is used to get the attributes of a data type
  940.         object.
  941.  
  942.      INPUTS
  943.         o     - Pointer to an object as returned by NewDTObjectA.
  944.                 A NULL arg is valid (V45).
  945.  
  946.         attrs - Attributes to get, terminated with TAG_DONE.  The data
  947.                 element of each pair contains the address of the storage
  948.                 variable.
  949.                 A NULL arg is valid (V45).
  950.  
  951.      TAGS
  952.         See datatypesclass/OM_GET and <datatypes/datatypesclass.h> for
  953.         attributes.
  954.  
  955.      RETURNS
  956.         retval - Contains the number of attributes the system was able
  957.                  to obtain.
  958.  
  959.      SEE ALSO
  960.         datatypesclass/OM_GET,
  961.         SetDTAttrsA,
  962.         intuition.library/GetAttr
  963.  
  964. datatypes.library/GetDTMethods                 datatypes.library/GetDTMethods
  965.  
  966.      NAME
  967.         GetDTMethods -- Obtain methods an object supports.       (V39)
  968.  
  969.      SYNOPSIS
  970.         methods = GetDTMethods( object );
  971.         d0                      a0
  972.  
  973.         ULONG *GetDTMethods( Object * );
  974.  
  975.      FUNCTION
  976.         This function is used to obtain a list of methods that an
  977.         object supports.
  978.  
  979.      INPUTS
  980.         object - Pointer to an object as returned by NewDTObjectA.
  981.                  NULL is a valid arg (V45).
  982.  
  983.      RETURNS
  984.         Returns a pointer to a ~0 terminated ULONG array.  This array
  985.         is only valid until the object is disposed off.
  986.  
  987.      NOTE
  988.         Some (interactive) objects may change the list of supported
  989.         methods during execution. This change is notified by
  990.         an OM_NOTIFY msg which contains the DTA_Sync tag.
  991.  
  992.      SEE ALSO
  993.         GetDTTriggerMethods,
  994.         FindMethod,
  995.         datatypesclass/OM_GET
  996.  
  997. datatypes.library/GetDTString                   datatypes.library/GetDTString
  998.  
  999.      NAME
  1000.         GetDTString -- Obtain a DataTypes string.                (V39)
  1001.  
  1002.      SYNOPSIS
  1003.         str = GetDTString( id );
  1004.         d0                 d0
  1005.  
  1006.         STRPTR GetDTString( ULONG );
  1007.  
  1008.      FUNCTION
  1009.         This function is used to obtain a pointer to a localized
  1010.         DataTypes string.
  1011.  
  1012.      INPUTS
  1013.         id - ID of the string to obtain.
  1014.  
  1015.      RETURNS
  1016.         A pointer to a NULL terminated string.
  1017.  
  1018.      NOTE
  1019.         - Error codes from 1-499 belongs to DOS, error codes from
  1020.           500-999 belongs to ENVOY and error codes from 2000-2099
  1021.           belongs to DataTypes. Codes between 2100 and 2999 are
  1022.           used to access localizes DataTypes strings.
  1023.  
  1024.         - Does not support the ENVOY error code nor the DOS error code space
  1025.           (use dos.library/Fault in this case).
  1026.  
  1027.      SEE ALSO
  1028.  
  1029. datatypes.library/GetDTTriggerMethodDataFlagsrary/GetDTTriggerMethodDataFlags
  1030.  
  1031.    NAME
  1032.         GetDTTriggerMethodDataFlags -- Get data type of dtt_Data value (V45)
  1033.  
  1034.    SYNOPSIS
  1035.         type = GetDTTriggerMethodDataFlags( method );
  1036.                                             d0
  1037.  
  1038.         ULONG GetDTTriggerMethodDataFlags( ULONG );
  1039.  
  1040.    FUNCTION
  1041.         This function returns the kind of data which can be attached
  1042.         to the stt_Data field in the dtTrigger method body.
  1043.  
  1044.         The data type can be specified by or'ing the method id (within
  1045.         STMF_METHOD_MASK value) with one of the STMD_#? identifiers:
  1046.  
  1047.         STMD_VOID    - stt_Data MUST be NULL
  1048.         STMD_ULONG   - stt_Data contains an unsigned long value
  1049.         STMD_STRPTR  - stt_Data is a string pointer
  1050.         STMD_TAGLIST - stt_Data points to an array of struct TagItem's,
  1051.                        terminated with TAG_DONE
  1052.  
  1053.         The trigger methods below STM_USER are explicitly handeled, as
  1054.         described in <datatypes/datatypesclass.h>, e.g. STM_COMMAND
  1055.         return STMD_STRPTR, instead of STMD_VOID.
  1056.  
  1057.    INPUTS
  1058.         method - dtt_Method ID from struct DTMethod
  1059.  
  1060.    RESULT
  1061.         type - one of the STMD_#? identifies in <datatypes/datatypesclass.h>
  1062.  
  1063.    EXAMPLE
  1064.         struct DTMethod htmldtc_dtm[] =
  1065.         {
  1066.           /* ... */
  1067.           "Stop Loading", "STOP",       (STM_STOP | STMD_VOID),
  1068.           "Load Images",  "LOADIMAGES", ((STM_USER + 20) | STMD_VOID),
  1069.           "Goto URL",     "GOTOURL",    ((STM_USER + 21) | STMD_STRPTR),
  1070.           /* ... */
  1071.           NULL,           NULL,         0L
  1072.         };
  1073.  
  1074.         Sets up three methods:
  1075.           "STOP" takes no arguments,
  1076.           "LOADIMAGES" takes no arguments and
  1077.           "GOTOURL" takes a STRPTR as an argument.
  1078.  
  1079.    SEE ALSO
  1080.         CopyDTTriggerMethods,
  1081.         FindTriggerMethod,
  1082.         datatypesclass/DTM_TRIGGER,
  1083.         "Examples/dtrequester/dtrequester.c",
  1084.         "Examples/CloneMethods/CloneMethods.c"
  1085.  
  1086. datatypes.library/GetDTTriggerMethods   datatypes.library/GetDTTriggerMethods
  1087.  
  1088.      NAME
  1089.         GetDTTriggerMethods -- Obtain trigger methods supported by an object
  1090.                                                                 (V39)
  1091.  
  1092.      SYNOPSIS
  1093.         methods = GetDTTriggerMethods( object );
  1094.         d0                             a0
  1095.  
  1096.         struct DTMethod *GetDTTriggerMethods( Object * );
  1097.  
  1098.      FUNCTION
  1099.         This function is used to obtain a list of trigger methods that an
  1100.         object supports.  This is so that an application can provide
  1101.         the appropriate controls (buttons etc.) for an object.  For example,
  1102.         an AmigaGuide object needs controls for "Contents", "Index",
  1103.         "Retrace", "Browse <", and "Browse >",
  1104.  
  1105.      INPUTS
  1106.         object - Pointer to an object as returned by NewDTObjectA.
  1107.                  NULL is a valid arg (V45).
  1108.  
  1109.      RETURNS
  1110.         Returns a pointer to a STM_DONE terminated DTMethod list.  This list
  1111.         is only valid until the object is disposed off.
  1112.  
  1113.      EXAMPLE
  1114.         To call the method:
  1115.  
  1116.         DoDTMethod( object, window, requester,
  1117.                     DTM_TRIGGER, NULL, (dtm[ button ] -> dtm_Method), NULL );
  1118.  
  1119.      WARNING
  1120.         Some trigger methods requires an argument. Calling them with
  1121.         a NULL argument is WRONG. Use GetDTTriggerMethodDataFlags to
  1122.         obtain the type of the requested argument (STMD_VOID means:
  1123.         no arguments).
  1124.  
  1125.      NOTE
  1126.         Some (interactive) objects may change the list of supported
  1127.         trigger methods during execution. This change is notified by
  1128.         an OM_NOTIFY msg which contains the DTA_Sync tag.
  1129.  
  1130.      SEE ALSO
  1131.         GetDTMethods,
  1132.         FindTriggerMethod,
  1133.         datatypesclass/OM_GET
  1134.  
  1135. datatypes.library/LaunchToolA                   datatypes.library/LaunchToolA
  1136.  
  1137.    NAME
  1138.         LaunchToolA -- invoke a given tool with project (V45)
  1139.  
  1140.    SYNOPSIS
  1141.         success = LaunchToolA( tool, project, attrs );
  1142.         d0                     a0    a1       a2
  1143.  
  1144.         ULONG LaunchToolA( struct Tool *, STRPTR, struct TagItem * );
  1145.  
  1146.         success = LaunchTool( tool, project, tag1, ... );
  1147.  
  1148.         ULONG LaunchTool( struct Tool *, STRPTR, ... );
  1149.  
  1150.    FUNCTION
  1151.         This function launches an application with a specified project.
  1152.         The application and it's launch mode and other attributes are
  1153.         specified through the "Tool" structure.
  1154.  
  1155.    INPUTS
  1156.         tool    - Pointer to a Tool structure
  1157.                   NULL is a valid arg.
  1158.  
  1159.         project - Name of the project to execute or NULL.
  1160.  
  1161.         attrs   - Additional attributes
  1162.  
  1163.    TAGS
  1164.         NP_Priority (BYTE) - sets the priority of the launched tool
  1165.             Defaults to the current process's priority for
  1166.             Shell and ARexx programs; Workbench applications
  1167.             defaults to 0 except overridden by the TOOLPRI tooltype.
  1168.  
  1169.         NP_Synchronous (BOOL) - don't return until lauched application proces
  1170. s
  1171.             finishes.
  1172.             Defaults to FALSE.
  1173.  
  1174.         Other tags are __currently__ ignored.
  1175.  
  1176.    RETURNS
  1177.         FALSE for failure, non-zero for success.
  1178.  
  1179.    EXAMPLE
  1180.         See "Examples/DoDT/DoDT.c".
  1181.  
  1182.    NOTE
  1183.         - This function requrires the "RX" command when lauching ARexx
  1184.           scripts.
  1185.  
  1186.         - This function must be launched from a process, not a simple task.
  1187.  
  1188.         - This function is not limitted to use the struct DataType -> dtn_Too
  1189. ls
  1190.           tools. Applications can set up their own struct Tool's as long
  1191.           as these structures contains no rubbish.
  1192.           If you don't know the TW_#? ("which") type of your custom tool, set
  1193.           tn_Which to TW_MISC.
  1194.  
  1195.    TODO
  1196.         - Should support multiple projects for WB programs.
  1197.  
  1198.         - Shell tools should have a setable stack size...
  1199.  
  1200.    BUGS
  1201.         - The WB launcher does not search the WB path for "Default Tools".
  1202.  
  1203.         - The "%a" (Arguments) option for shell launched tools does
  1204.           currently not work.
  1205.           Will be fixed.
  1206.  
  1207.         - The path of the launched tools depends on the parents path.
  1208.           If there is no path, shell tools can only launch other tools
  1209.           with their full path.
  1210.  
  1211.    SEE ALSO
  1212.         FindToolNodeA
  1213.  
  1214. datatypes.library/LockDataType                 datatypes.library/LockDataType
  1215.  
  1216.      NAME
  1217.         LockDataType -- Lock a DataType structure.         (V45)
  1218.  
  1219.      SYNOPSIS
  1220.         LockDataType( dtn );
  1221.                       a0
  1222.  
  1223.         VOID LockDataType( struct DataType * );
  1224.  
  1225.      FUNCTION
  1226.         This function is used to lock a DataType structure obtained
  1227.         by ObtainDataTypeA or a datatypes object (DTA_DataType attribute).
  1228.  
  1229.         All calls to LockDataType or ObtainDataTypeA must match the same
  1230.         number of ReleaseDataType calls, otherwise havoc will break out.
  1231.  
  1232.      INPUTS
  1233.         dtn - DataType structure returned by ObtainDataTypeA. NULL
  1234.               is a valid input.
  1235.  
  1236.      NOTE
  1237.         This function has been made public to allow to get a DataType
  1238.         structure from an object (DTA_DataType attribute), and remain the
  1239.         reference valid after the object has been disposed off (which
  1240.         unlocks the DataType structure locked in NewDTObjectA).
  1241.  
  1242.      SEE ALSO
  1243.         ObtainDataTypeA, ReleaseDataType
  1244.  
  1245. datatypes.library/NewDTObjectA                 datatypes.library/NewDTObjectA
  1246.  
  1247.      NAME
  1248.         NewDTObjectA -- Create an data type object.              (V39)
  1249.  
  1250.      SYNOPSIS
  1251.         o = NewDTObjectA( name, attrs );
  1252.         d0                d0   a0
  1253.  
  1254.         Object *NewDTObjectA( APTR, struct TagItem * );
  1255.  
  1256.         o = NewDTObject( name, tag1, ... );
  1257.  
  1258.         Object *NewDTObject( APTR, Tag, ... );
  1259.  
  1260.      FUNCTION
  1261.         This is the method for creating datatype objects from
  1262.         'boopsi' classes. (Boopsi' stands for "basic object-oriented
  1263.         programming system for Intuition".)
  1264.  
  1265.         You further specify initial "create-time" attributes for the
  1266.         object via a TagItem list, and they are applied to the
  1267.         resulting datatype object that is returned.
  1268.  
  1269.      INPUTS
  1270.         name  - Name of the data source.  Usually an existing file name.
  1271.  
  1272.         attrs - Pointer to a taglist containing additional arguments.
  1273.  
  1274.      TAGS
  1275.         DTA_SourceType (ULONG) - Specify the type of source data;
  1276.             such as coming from a file or clipboard.  If source type is
  1277.             clipboard, then the name field contains the numeric clipboard
  1278.             unit.
  1279.             Defaults to DTST_FILE.
  1280.  
  1281.         DTA_Handle - Can optionally be used instead of the name field.
  1282.             Must be a valid Lock (BPTR) if DTA_SourceType is DTST_FILE.
  1283.             Must be a valid IFFHandle (struct IFFHandle *) if DTA_SourceType
  1284.             is DTST_CLIPBOARD.
  1285.             Must be NULL if DTA_SourceType is DTST_RAM.
  1286.  
  1287.         DTA_DataType (struct DataType *) - Specify the class of data.
  1288.             Data is a pointer to a valid DataType.  This is only used when
  1289.             attempting to create a new object that doesn't have any source
  1290.             data or to force the library to use this class to handle the data
  1291. .
  1292.             The datatype given will not be unlocked.
  1293.             Defaults to NULL (use ObtainDataTypeA to determinate the file/
  1294.             clipboard contents type).
  1295.  
  1296.         DTA_BaseName (STRPTR) (V45) - Specify base name of datatype to use.
  1297.             This tag should be used rarely (e.g. if a matching descriptor
  1298.             does not exists). It must only be used with DTST_RAM.
  1299.             Passing both DTA_BaseName and DTA_DataType causes havoc and must
  1300.             be avoided.
  1301.  
  1302.         DTA_Class (struct IClass *) (V45.3) - Specify the class to create an
  1303.             object from. Usefull when creating private subclasses inside 
  1304.             applications (e.g. when a subclass is needed to superset some 
  1305.             methods (see "DTConvert" example)).
  1306.  
  1307.         DTA_GroupID (ULONG) - Specify that the object must be of this type, o
  1308. r
  1309.             NewDTObjectA will fail with IoErr of
  1310.             ERROR_OBJECT_WRONG_TYPE.
  1311.             Defaults to 0 (no specific group).
  1312.  
  1313.  
  1314.         The following list is a collection of attributes recognized by some
  1315.         subclasses. The "Defaults to" are only suggestions, and may or may
  1316.         not have this value for a specific class:
  1317.  
  1318.         DTA_TextAttr (struct TextAttr *) - Specify the default object font
  1319.             which should be used.
  1320.             Defaults to NULL.
  1321.  
  1322.         DTA_NodeName (STRPTR) - Specify the node to load (for those
  1323.             datatypes which splits their data into nodes, such as AmigaGuide
  1324.             or SGML).
  1325.             Defaults to "Main", which means the "Main" entry of the document.
  1326.  
  1327.         DTA_Conductor (STRPTR) - specifies the name of the
  1328.             realtime.library conductor (for syncronisation of events).
  1329.             Defaults to (~0UL) (private conductor).
  1330.  
  1331.         DTA_ControlPanel (BOOL) - Indicate whether a control panel should be
  1332.             embedded within the object (like animation.datatype, for
  1333.             example).
  1334.             Defaults to TRUE.
  1335.  
  1336.         DTA_Immediate (BOOL) - Indicate whether the object should immediate
  1337.             begin playing.
  1338.             Defaults to FALSE.
  1339.  
  1340.         DTA_Repeat (BOOL) - Indicate whether the object should repeat playing
  1341.             (the sound, sample, music or animation).
  1342.             Defaults to FALSE.
  1343.  
  1344.         DTA_ARexxPortName (STRPTR) - Base name for ARexx port
  1345.             Defaults to
  1346.             "<(struct DataTypesHeader -> dth_BaseName)>.<unique count>".
  1347.  
  1348.         DTA_Progressive (BOOL) - Use progressive loading, if possible.
  1349.             Defaults to FALSE.
  1350.  
  1351.         GA_Left, GA_RelRight, GA_Top, GA_RelBottom, GA_Width, GA_RelWidth,
  1352.         GA_Height, GA_RelHeight (WORD) - Specify the placement of the object
  1353.             within the destination window.
  1354.  
  1355.         GA_ID (UWORD) - Specify the object ID.
  1356.  
  1357.         GA_UserData (ULONG) - Specify the application specific data for the
  1358.             object.
  1359.  
  1360.         DTA_UserData (ULONG) - Specify the application specific data for the
  1361.             object.
  1362.  
  1363.      RETURNS
  1364.         A boopsi object, which may be used in different contexts such
  1365.         as a gadget or image, and may be manipulated by generic functions.
  1366.         You eventually free the object using DisposeDTObject.
  1367.  
  1368.         A NULL return indicates failure.  Use IoErr to get error value.
  1369.         Following is a summary of the error number used and there meaning
  1370.         as it relates to DataTypes.
  1371.  
  1372.         ERROR_REQUIRED_ARG_MISSING - Indicates that a required attribute
  1373.             wasn't passed in.
  1374.  
  1375.         ERROR_BAD_NUMBER - An invalid group ID was passed in.
  1376.  
  1377.         ERROR_OBJECT_WRONG_TYPE - Object data type doesn't match
  1378.             DTA_GroupID.
  1379.  
  1380.         ERROR_NO_FREE_STORE - Not enough memory.
  1381.  
  1382.         DTERROR_UNKNOWN_DATATYPE - Unable to open the class library
  1383.             associated with the data type.
  1384.  
  1385.         DTERROR_COULDNT_OPEN - Unable to open the data object.
  1386.  
  1387.         ERROR_NOT_IMPLEMENTED - Unknown handle type.
  1388.  
  1389.      NOTES
  1390.         This function invokes the OM_NEW "method" for the class specified.
  1391.  
  1392.      EXAMPLE
  1393.         STRPTR  FileName = "S:User-Startup"
  1394.         Object *o;
  1395.  
  1396.         /* Simplest way is just to open an existing file */
  1397.         if( o = NewDTObjectA( (APTR)FileName, NULL ) )
  1398.         {
  1399.           /* ... */
  1400.  
  1401.           /* Get rid of the object when we are done with it */
  1402.           DisposeDTObject( o );
  1403.         }
  1404.  
  1405.      BUGS
  1406.         Before V45, creating a blank text object using
  1407.         { DTA_SourceType, DTSR_RAM },
  1408.         { DTA_GroupID,    GID_TEXT },
  1409.         tags, an "ascii.datatype" object was returned. Starting with
  1410.         V45, NewDTObjectA returns now correctly a "text.datatype" object.
  1411.  
  1412.      SEE ALSO
  1413.         AddDTObject, DisposeDTObject, RemoveDTObject,
  1414.         intuition.library/NewObjectA,
  1415.         datatypesclass/OM_NEW
  1416.  
  1417. datatypes.library/ObtainDataTypeA           datatypes.library/ObtainDataTypeA
  1418.  
  1419.      NAME
  1420.         ObtainDataTypeA -- Examines a handle and return its DataType. (V39)
  1421.  
  1422.      SYNOPSIS
  1423.         dtn = ObtainDataTypeA( type, handle, attrs );
  1424.         d0                     d0    a0      a1
  1425.  
  1426.         struct DataType *ObtainDataTypeA( ULONG, APTR, struct TagItem * );
  1427.  
  1428.         dtn = ObtainDataType( type, handle, tag1, ... );
  1429.  
  1430.         struct DataType *ObtainDataType( ULONG, APTR, Tag, ... );
  1431.  
  1432.      FUNCTION
  1433.         This function examines the data that the handle points to,
  1434.         and returns a DataType record that describes the data.
  1435.  
  1436.      INPUTS
  1437.         type   - Type of handle (one of the DTST_#? handle types).
  1438.  
  1439.         handle - Handle to examine.
  1440.             For DTST_FILE,      handle must be BPTR lock.
  1441.             For DTST_CLIPBOARD, handle must be struct IFFHandle *.
  1442.             For DTST_RAM (V45), handle must be a STRPTR (DataType
  1443.                                 name, equals to the dtn_Name field).
  1444.             For DTST_HOTLINK    NOT IMPLEMENTED YET
  1445.  
  1446.             The handle given will not be unlocked/freed.
  1447.  
  1448.         attrs  - Additional attributes.
  1449.             DTA_GroupID  (ULONG) (V45) - GID_#? group to match
  1450.                                  0 is a valid input.
  1451.  
  1452.             DTA_DataType (struct DataType *) (V45) - Search in descriptor
  1453.                                  list starts at this point (maybe result
  1454.                                  of a previous datatype).
  1455.                                  The given datatype will NOT be unlocked.
  1456.                                  NULL is a valid input (start at the begin
  1457.                                  of list).
  1458.  
  1459.      NOTES
  1460.         - The datatypes.library maintains a sorted list of all the DataType
  1461.           descriptors.  The descriptor can consist of a function, a data mask
  1462.           for the first 64 bytes of the data, and a name pattern.
  1463.  
  1464.           The sort order for the list is:
  1465.  
  1466.             Descriptors with a function and no mask or name pattern.
  1467.             Descriptors with a function and a mask or name pattern.
  1468.             Descriptors with no function and a mask or name pattern.
  1469.  
  1470.           Within each group, they are also sorted in descending priority
  1471.           and descending mask length.
  1472.  
  1473.         - ObtainDataTypeA calls with same parameters may return a different
  1474.           struct DataType *. 
  1475.           Same datatypes have the same dth_Name
  1476.  
  1477.      RETURNS
  1478.         Success returns a pointer to a DataType. You must call
  1479.         ReleaseDataType when you are done with the handle.
  1480.  
  1481.         A NULL return indicates failure.  Use IoErr to get error value.
  1482.         Following is a summary of the error number used and there meaning
  1483.         as it relates to DataTypes.
  1484.  
  1485.         ERROR_NO_FREE_STORE    - Not enough memory.
  1486.  
  1487.         DTERROR_COULDNT_OPEN   - Unable to open the data object.
  1488.  
  1489.         ERROR_NOT_IMPLEMENTED  - Unknown handle type.
  1490.  
  1491.         ERROR_INVALID_LOCK     - DTA_DataType attribute passed in
  1492.                                  wasn't valid (V45).
  1493.  
  1494.      BUGS
  1495.         Before V45, passing a user-defined struct DataType (e.g. the
  1496.         dtn_Length is 0UL) to datatypes.library functions may causes
  1497.         crashes.
  1498.  
  1499.      EXAMPLE
  1500.         See "Examples/dtdescrlist/dtdescrlist.c"
  1501.  
  1502.      SEE ALSO
  1503.         ReleaseDataType, LockDataType,
  1504.         "Examples/dtdescrlist/dtdescrlist.c"
  1505.  
  1506. datatypes.library/ObtainDTDrawInfoA       datatypes.library/ObtainDTDrawInfoA
  1507.  
  1508.    NAME
  1509.        ObtainDTDrawInfoA -- Obtain a DataTypes object for drawing. (V39)
  1510.  
  1511.    SYNOPSIS
  1512.        handle = ObtainDTDrawInfoA( o, attrs );
  1513.        d0                          a0  a1
  1514.  
  1515.        APTR ObtainDTDrawInfoA( Object *, struct TagItem * );
  1516.  
  1517.        handle = ObtainDTDrawInfo( o, tag1, ... );
  1518.  
  1519.        APTR ObtainDTDrawInfo( Object *, Tag, ... );
  1520.  
  1521.    FUNCTION
  1522.        This function is used to prepare a DataTypes object for
  1523.        drawing into a RastPort.
  1524.  
  1525.        This function will send the DTM_OBTAINDRAWINFO method
  1526.        to the object using the opSet message structure.
  1527.  
  1528.    INPUTS
  1529.        o     - Pointer to an object as returned by NewDTObjectA.
  1530.                Starting with V45, a NULL arg results in a NOP.
  1531.  
  1532.        attrs - Additional attributes.
  1533.  
  1534.    RETURNS
  1535.        Returns a PRIVATE handle that must be passed to ReleaseDTDrawInfo
  1536.        when the application is done drawing the object.
  1537.        A NULL return value indicates failure.
  1538.  
  1539.    TAGS
  1540.        Good args are
  1541.        PDTA_Screen for pictureclass objects and
  1542.        ADTA_Screen for animationclass objects.
  1543.  
  1544.    EXAMPLE
  1545.        See "Examples/dtimage/dtimage.c".
  1546.  
  1547.    NOTE
  1548.        You cannot handle the same datatypesclass object as a gadget in
  1549.        a window/requester and as a image using ObtainDTDrawInfoA/
  1550.        DrawDTObjectA/ReleaseDTDrawInfo at the same time.
  1551.        But using it as a gadget, then remove it from window, then use it as
  1552.        an image is valid and __must__ be supported.
  1553.  
  1554.    SEE ALSO
  1555.        DrawDTObjectA, ReleaseDTDrawInfo,
  1556.        "Examples/dtimage/dtimage.c"
  1557.  
  1558. datatypes.library/PrintDTObjectA             datatypes.library/PrintDTObjectA
  1559.  
  1560.      NAME
  1561.         PrintDTObjectA -- Call the DTM_PRINT method on a separate process.
  1562.                                                                 (V39)
  1563.  
  1564.      SYNOPSIS
  1565.         retval = PrintDTObjectA( object, window, requester, msg );
  1566.         d0                       a0      a1      a2         a3
  1567.  
  1568.         ULONG PrintDTObjectA( Object *, struct Window *, struct Requester *,
  1569.                               struct dtPrint * );
  1570.  
  1571.         retval = PrintDTObject( object, window, requester, data, ... );
  1572.  
  1573.         ULONG PrintDTObject( Object *, struct Window *, struct Requester *,
  1574.                              ULONG, ... );
  1575.  
  1576.      FUNCTION
  1577.         This function is used to asyncronously perform the object's DTM_PRINT
  1578.         method.
  1579.  
  1580.         Once the application has performed the PrintDTObjectA function,
  1581.         it must not manipulate the printerIO union until it receives a
  1582.         OM_UPDATE message that contains the DTA_PrinterStatus tag.
  1583.  
  1584.         To abort a print, the application sends the DTM_ABORTPRINT method
  1585.         to the object.  This in turn signals the print process with a
  1586.         SIGBREAKF_CTRL_C.
  1587.  
  1588.         Starting with V45, the stack size of the print daemon process
  1589.         increases from 4096 up to 8192 bytes.
  1590.  
  1591.      INPUTS
  1592.         object    - Pointer to the DataTypes object.
  1593.  
  1594.         window    - Pointer to the window that the object has been added to.
  1595.  
  1596.         requester - Pointer to the requester that the object has been
  1597.                     added to (V45).
  1598.  
  1599.         msg       - Pointer to struct dtPrint message
  1600.  
  1601.      RETURNS
  1602.         Returns TRUE if successful, FALSE on error (anoter print in process).
  1603.  
  1604.      NOTE
  1605.         When the DTM_PRINT method is done, the print daemon triggers a notify
  1606.         msg with following contents:
  1607.  
  1608.         { GA_ID,             GadgetID         },
  1609.         { DTA_PrinterStatus, dtm_print_retval }
  1610.  
  1611.      SEE ALSO
  1612.         datatypesclass/DTM_PRINT,
  1613.         datatypesclass/DTM_ABORTPRINT
  1614.  
  1615. datatypes.library/RefreshDTObjectA         datatypes.library/RefreshDTObjectA
  1616.  
  1617.      NAME
  1618.         RefreshDTObjectA -- Refresh a datatypes object.          (V39)
  1619.  
  1620.      SYNOPSIS
  1621.         RefreshDTObjectA( object, window, req, attrs )
  1622.                           a0      a1      a2   a3
  1623.  
  1624.         VOID RefreshDTObjectA( Object *, struct Window *,
  1625.                                 struct Requester *, struct TagItem * );
  1626.  
  1627.         RefreshDTObject( object, window, req, tag1, ... );
  1628.  
  1629.         VOID RefreshDTObject( Object *, struct Window *,
  1630.                                struct Requester *, Tag, ... );
  1631.  
  1632.      FUNCTION
  1633.         Refreshes the specified object, by sending the GM_RENDER method to
  1634.         the object.
  1635.  
  1636.      INPUTS
  1637.         object - Pointer to an object as returned by NewDTObjectA.
  1638.                  NULL is a valid arg (V45).
  1639.  
  1640.         window - Pointer to the window.
  1641.                  NULL is a valid arg (V45).
  1642.  
  1643.         req    - Pointer to the requester (V45).
  1644.  
  1645.         attrs  - Additional attributes (currently none are defined).
  1646.  
  1647.      SEE ALSO
  1648.         AddDTObject, RemoveDTObject,
  1649.         intuition.library/RefreshGList
  1650.  
  1651. datatypes.library/ReleaseDataType           datatypes.library/ReleaseDataType
  1652.  
  1653.      NAME
  1654.         ReleaseDataType -- Release a DataType structure.         (V39)
  1655.  
  1656.      SYNOPSIS
  1657.         ReleaseDataType( dtn );
  1658.                          a0
  1659.  
  1660.         VOID ReleaseDataType( struct DataType * );
  1661.  
  1662.      FUNCTION
  1663.         This function is used to release a DataType structure obtained
  1664.         by ObtainDataTypeA.
  1665.  
  1666.      INPUTS
  1667.         dtn - DataType structure returned by ObtainDataTypeA.  NULL
  1668.               is a valid input.
  1669.  
  1670.      BUGS
  1671.         Before V45, passing a user-defined struct DataType (e.g. the
  1672.         dtn_Length is 0UL) may causes crashes.
  1673.  
  1674.      NOTE
  1675.         Starting with V45.4, ReleaseDataType throws an Alert (AN_Unknown)
  1676.         if a mismatched (e.g. too many ReleaseDataType's) ReleaseDataType
  1677.         was triggered.
  1678.  
  1679.      SEE ALSO
  1680.         ObtainDataTypeA, LockDataType
  1681.  
  1682. datatypes.library/ReleaseDTDrawInfo       datatypes.library/ReleaseDTDrawInfo
  1683.  
  1684.    NAME
  1685.        ReleaseDTDrawInfo -- Release a DataTypes object from drawing. (V39)
  1686.  
  1687.    SYNOPSIS
  1688.        ReleaseDTDrawInfo( o, handle );
  1689.                           a0 a1
  1690.  
  1691.        VOID ReleaseDTDrawInfo( Object *, APTR );
  1692.  
  1693.    FUNCTION
  1694.        This function is used to release the information obtained
  1695.        with ObtainDTDrawInfoA.
  1696.  
  1697.        This function invokes the object's DTM_RELEASEDRAWINFO method
  1698.        using the dtReleaseDrawInfo message structure.
  1699.  
  1700.    INPUTS
  1701.        o      - Object returned by NewDTObjectA.
  1702.                 Starting with V45, a NULL arg results in a NOP.
  1703.  
  1704.        handle - Pointer to an private handle obtained by ObtainDTDrawInfoA.
  1705.  
  1706.    EXAMPLE
  1707.        See "Examples/dtimage/dtimage.c".
  1708.  
  1709.    SEE ALSO
  1710.        DrawDTObjectA, ObtainDTDrawInfoA,
  1711.        "Examples/dtimage/dtimage.c".
  1712.  
  1713. datatypes.library/RemoveDTObject             datatypes.library/RemoveDTObject
  1714.  
  1715.      NAME
  1716.         RemoveDTObject -- Remove an object from a window.        (V39)
  1717.  
  1718.      SYNOPSIS
  1719.         position = RemoveDTObject( window, object );
  1720.         d0                         a0      a1
  1721.  
  1722.         LONG RemoveDTObject( struct Window *, Object * );
  1723.  
  1724.      FUNCTION
  1725.         Removes the object from the window's object list.  This will wait
  1726.         until the AsyncLayout process is complete.  The object will
  1727.         receive a DTM_REMOVEDTOBJECT message to inform the object will
  1728.         be removed.
  1729.         If the gadget was in a requester, the GTYP_REQGADGET flag will
  1730.         be cleared.
  1731.  
  1732.      INPUTS
  1733.         window - Pointer to the window.
  1734.  
  1735.         object - Pointer to an object as returned by NewDTObjectA.
  1736.                  NULL is a valid arg (V45).
  1737.  
  1738.      RETURNS
  1739.         Returns the ordinal position of the removed object.  If the
  1740.         object wasn't found in the appropriate list then a -1 is
  1741.         returned.
  1742.  
  1743.      NOTE
  1744.         Note that this function __MUST__ not be uses when a datatype
  1745.         object is embedded within another BOOPSI gadget. The
  1746.         parent object is responsible to pass all required methods
  1747.         including initial GM_LAYOUT and DTM_REMOVEDTOBJECT to
  1748.         the embedded object.
  1749.  
  1750.      SEE ALSO
  1751.         AddDTObject, 
  1752.         intuition.library/RemoveGList,
  1753.         datatypesclass/DTM_REMOVEDTOBJECT
  1754.  
  1755. datatypes.library/rexx/--rexxhost--       datatypes.library/rexx/--rexxhost--
  1756.  
  1757.  
  1758.     HOST INTERFACE
  1759.         datatypes.library provides an ARexx function host interface that
  1760.         enables ARexx programs to take advantage of the features of data
  1761.         types.  The functions provided by the interface are directly
  1762.         related to the functions described herein, with the differences
  1763.         mostly being in the way they are called.
  1764.  
  1765.         The function host library vector is located at offset -30 from
  1766.         the library. This is the value you provide to ARexx in the
  1767.         ARexx AddLib function call.
  1768.  
  1769.     FUNCTIONS
  1770.         EXAMINEDT  - Examine file
  1771.  
  1772.         OBTAINDATATYPE  - Obtain datatype from a given file, clipboard or
  1773.                      by other specs
  1774.  
  1775.         FINDTTOOL  - Find a tool by name, type etc.
  1776.  
  1777.         LAUNCHTOOL - Launch a tool
  1778.  
  1779.         OBTAINDTSTRING - Obtain datatypes string
  1780.  
  1781.         (DEBUG      - __PRIVATE__ (Debugging control))
  1782.  
  1783.  
  1784. datatypes.library/rexx/EXAMINEDT             datatypes.library/rexx/EXAMINEDT
  1785.  
  1786.     NAME
  1787.         EXAMINEDT -- Examine given file
  1788.  
  1789.     SYNOPSIS
  1790.         EXAMINEDT( FILENAME/A, STEM, STORAGE )
  1791.  
  1792.     FUNCTION
  1793.         EXAMINEDT obtains data type and other attributes of the given
  1794.         filesystem object.
  1795.  
  1796.     INPUTS
  1797.         FILENAME - filesystem object (file/dir/etc.) to examine
  1798.  
  1799.         STEM - Name of stem variable to store data in
  1800.  
  1801.         STORAGE - Type of result storage, one of "STEM" or "VAR"
  1802.  
  1803.     RESULTS
  1804.         If STORAGE was set to "VAR", the result is the datatype name.
  1805.         On error, the numeric DOS error code is returned.
  1806.  
  1807.         If STORAGE was set to "STEM" (and a stem var was given), the
  1808.         stem var has the following members:
  1809.  
  1810.         DISKKEY           Filesystem disk key
  1811.  
  1812.         DIRENTRYTYPE      Dir Entry Type, one of
  1813.                           1   root directory (for UNIX fs)
  1814.                           2   directory
  1815.                           3   soft link (looks like dir, but may point to a
  1816.                               file !)
  1817.                           4   hard link to directory
  1818.                          -3  file
  1819.                          -4  hard link to file
  1820.                          -5  pipe file
  1821.  
  1822.         FILENAME          File Name
  1823.  
  1824.         PROTECTION        Protection
  1825.  
  1826.         OTHERPROTECTION   Other Protection
  1827.  
  1828.         GROUPPROTECTION   Group Protection
  1829.  
  1830.         ENTRYTYPE         Entry Type, see DIRENTRYTYPE for types
  1831.  
  1832.         SIZE              Size of file in bytes
  1833.  
  1834.         NUMBLOCKS         Blocks
  1835.  
  1836.         DATE              Date (AmigaDOS style)
  1837.  
  1838.         COMMENT           Comment
  1839.  
  1840.         OWNERUID          Owner User ID
  1841.  
  1842.         OWNERGID          Owner Group ID
  1843.  
  1844.         OWNERUIDNAME      Owner User Name
  1845.  
  1846.         OWNERGIDNAME      Owner Group Name
  1847.  
  1848.         BASETYPE          Type, one of "binary", "ascii", "iff" or "other"
  1849.  
  1850.         BASETYPENAME      Localiued form of BASETYPE
  1851.  
  1852.         DATATYPE          File Type
  1853.  
  1854.         BASENAME          Base Name
  1855.  
  1856.         GROUPID           DataTypes GroupID, like "syst", "text", "docu",
  1857.                           ...
  1858.  
  1859.         GROUPIDNAME       Localized format of GROUPID, like "System", "Text",
  1860.                           "Document", ...
  1861.  
  1862.         The function result contains the error code, (0 on success,
  1863.         1 - 2099 otherwise).
  1864.  
  1865.  
  1866.     EXAMPLE
  1867.         /* examinedt.rexx */
  1868.         PARSE ARG fname
  1869.         OPTIONS RESULTS
  1870.  
  1871.         /* Load the datatypes.library as a function host */
  1872.         IF ~SHOW( 'L', 'datatypes.library' ) THEN
  1873.            CALL ADDLIB( 'datatypes.library', 0, -30 )
  1874.  
  1875.            IF fname="" THEN DO
  1876.               SAY "Usage:"
  1877.               SAY "  rx examinedt <filename>"
  1878.               EXIT
  1879.            END
  1880.  
  1881.            SAY 'var test'
  1882.            type = ExamineDT( fname,,VAR )
  1883.            SAY type
  1884.  
  1885.            SAY 'stem test'
  1886.            CALL ExamineDT( fname, dtstem., STEM )
  1887.  
  1888.            SAY '         Disk Key:' dtstem.DiskKey
  1889.            SAY '   Dir Entry Type:' dtstem.DirEntryType
  1890.            SAY '        File Name:' dtstem.FileName
  1891.            SAY '       Protection:' dtstem.Protection
  1892.            SAY ' Other Protection:' dtstem.OtherProtection
  1893.            SAY ' Group Protection:' dtstem.GroupProtection
  1894.            SAY '       Entry Type:' dtstem.EntryType
  1895.            SAY '             Size:' dtstem.Size
  1896.            SAY '           Blocks:' dtstem.NumBlocks
  1897.            SAY '             Date:' dtstem.Date
  1898.            SAY '          Comment:' dtstem.Comment
  1899.            SAY '    Owner User ID:' dtstem.OwnerUID
  1900.            SAY '   Owner Group ID:' dtstem.OwnerGID
  1901.            SAY '  Owner User Name:' dtstem.OwnerUIDName
  1902.            SAY ' Owner Group Name:' dtstem.OwnerGIDName
  1903.            SAY '             Type:' dtstem.BaseType
  1904.            SAY '        File Type:' dtstem.DataType
  1905.            SAY '        Base Name:' dtstem.BaseName
  1906.            SAY '       DT GroupID:' dtstem.GroupID
  1907.         EXIT
  1908.  
  1909.     NOTE
  1910.         - Owner User Name and Owner Group Name requires fs support for
  1911.           ACTION_UID2UNAME and ACTION_GID2GNAME (like envoy fs).
  1912.  
  1913.         - Error handling has been changed in V45. On error, the function
  1914.           now returns the error number (1 - 2099), which can be converted
  1915.           using rexx/GETDTSTRING; only serious errors (like "non memory")
  1916.           will end in a rexx error code.
  1917.  
  1918.     SEE ALSO
  1919.         rexx/OBTAINDATATYPE
  1920.  
  1921. datatypes.library/rexx/FINDTOOL               datatypes.library/rexx/FINDTOOL
  1922.  
  1923.     NAME
  1924.         FINDTOOL -- Find a single tool stem from given pattern
  1925.  
  1926.     SYNOPSIS
  1927.         FINDTOOL( TOOLLISTSTEM/A, START/N, PROGRAM, WHICH, LAUNCHTYPE )
  1928.  
  1929.     FUNCTION
  1930.         Find a single tool stem within a TOOLLIST stem as returned by
  1931.         OBTAINDATATYPE
  1932.  
  1933.     INPUTS
  1934.         TOOLLISTSTEM -- a stem variable with TOOL stems and a TOOLLIST.COUNT
  1935.             var.
  1936.  
  1937.         START   - Start index, beginning from 0.
  1938.                   Note that the goven index will be skipped, and the search
  1939.                   starts at the following node.
  1940.                   Defaults to -1 (e.g. next node is 0).
  1941.  
  1942.         WHICH   - Type of application
  1943.                   One of "misc", "info", "browse", "edit", "print",
  1944.                   "mail".
  1945.                   Defaults to "", which means: Match all Which-Types
  1946.  
  1947.         LAUNCH  - Launch mode, one of "shell", "workbench", "rx"
  1948.                   Defaults to "", which means: Match all Launch-modes
  1949.  
  1950.         PROGRAM - Full path of the program to be launched
  1951.  
  1952.     RETURNS
  1953.         The index of the toolstem found or -1.
  1954.  
  1955.     EXAMPLE
  1956.  
  1957.     NOTE
  1958.  
  1959.     SEE ALSO
  1960.         rexx/OBTAINDATATYPE
  1961.  
  1962. datatypes.library/rexx/GETDTSTRING         datatypes.library/rexx/GETDTSTRING
  1963.  
  1964.     NAME
  1965.         GETDTSTRING -- Get (localized) datatypes string
  1966.  
  1967.     SYNOPSIS
  1968.         GETDTSTRING( ID/A, NAME )
  1969.  
  1970.     FUNCTION
  1971.         Gets a (localized) datatypes string and returns it in RESULT.
  1972.  
  1973.     INPUTS
  1974.         ID -- string number, like DTERROR_#? from
  1975.             include:datatypes/datatypes.h
  1976.             2000 - "Unknown data type for %s"
  1977.             and so on...
  1978.  
  1979.             or 
  1980.  
  1981.             one of "syst#?", "docu#?", ...
  1982.  
  1983.             or
  1984.  
  1985.             one of "binary", "ascii", "iff", "other" (or "Miscellaneous")
  1986.  
  1987.             Error codes from 1-499 belongs to DOS, error codes from
  1988.             500-999 belongs to ENVOY and error codes from 2000-2099
  1989.             belongs to DataTypes. Codes between 2100 and 2999 are
  1990.             used to access localizes DataTypes strings.
  1991.  
  1992.         NAME -- Name be be inserted into the string
  1993.  
  1994.     RETURNS
  1995.         string
  1996.  
  1997.     EXAMPLE
  1998.  
  1999.     NOTE
  2000.         - Does not support the envoy error code space.
  2001.  
  2002.     SEE ALSO
  2003.  
  2004. datatypes.library/rexx/LAUNCHTOOL           datatypes.library/rexx/LAUNCHTOOL
  2005.  
  2006.     NAME
  2007.         LAUNCHTOOL -- Lauch a tool from given spec
  2008.  
  2009.     SYNOPSIS
  2010.         LAUNCHTOOL( TOOLSTEM/A, PROJECT, SYNCHRONOUS=SYNC/S, PRIORITY/N )
  2011.  
  2012.     FUNCTION
  2013.         Lauch a tool with an argument (e.g. project file). As set by the
  2014.         TOOL stem, the tool may be lauched from Shell, from Workbench or
  2015.         from ARexx.
  2016.  
  2017.     INPUTS
  2018.         TOOLSTEM -- a stem variable with following members
  2019.             (this stem var is normally set up by OBTAINDATATYPE (TOOLLIST
  2020.             stem)):
  2021.             WHICH   - Type of application
  2022.                       One of "misc", "info", "browse", "edit", "print",
  2023.                       "mail".
  2024.                       If you don't know the "which"-type  of your tool,
  2025.                       set this to "misc".
  2026.  
  2027.             LAUNCH  - Launch mode, one of "shell", "workbench", "rx"
  2028.  
  2029.             PROGRAM - Full path of the program to be launched
  2030.  
  2031.         PROJECT  -- Name of the project file to be used (passed as
  2032.             an argument to the appliaction).
  2033.  
  2034.         SYNCHRONOUS
  2035.         SYNC     -- Wait for child exit ?
  2036.             If set, LaunchTool waits until the invoked program quits.
  2037.  
  2038.         PRIORITY -- Set task priority of the lauched application.
  2039.  
  2040.     RETURNS
  2041.         Success or failure
  2042.  
  2043.     EXAMPLE
  2044.  
  2045.     NOTE
  2046.  
  2047.     SEE ALSO
  2048.         rexx/OBTAINDATATYPE
  2049.  
  2050. datatypes.library/rexx/OBTAINDATATYPE   datatypes.library/rexx/OBTAINDATATYPE
  2051.  
  2052.     NAME
  2053.         OBTAINDATATYPE -- Obtain datatype from given #?
  2054.  
  2055.     SYNOPSIS
  2056.         OBTAINDATATYPE( TYPE/A, HANDLE/A, STEM/A, DATATYPE, GID )
  2057.  
  2058.     FUNCTION
  2059.  
  2060.     INPUTS
  2061.         TYPE -- Type of HANDLE data
  2062.             One of "RAM", "CLIPBOARD", "FILE" or "HOTLINK"
  2063.  
  2064.         HANDLE -- Handle type.
  2065.             For TYPE = "RAM", this is the DataType name to be searched
  2066.                 for. An empty string is treated as an NULL arg.
  2067.  
  2068.             For TYPE = "CLIPBOARD", this is the numeric clipboard unit.
  2069.  
  2070.             For TYPE = "FILE", this is the full path of a file/dir
  2071.                 to be examined.
  2072.  
  2073.             TYPE = "HOTLINK" is not implemented yet.
  2074.  
  2075.         STEM -- Name of the result stem var
  2076.  
  2077.         DATATYPE -- Name of the datatype to start at. Used when scanning
  2078.             the descriptor list.
  2079.  
  2080.         GID -- Group ID filter, one of "System", "Text", "Document", "Sound",
  2081.             "Instrument", "Music", "Picture", "Animation", "Movie".
  2082.             If set, only descriptors of this type will be returned.
  2083.  
  2084.     RETURNS
  2085.         Success or failure
  2086.  
  2087.         The given stem var has the following members:
  2088.  
  2089.         HEADER.NAME     - Name of the descriptor
  2090.  
  2091.         HEADER.BASENAME - Base name (class library name)
  2092.  
  2093.         HEADER.PATTERN  - File pattern
  2094.  
  2095.         HEADER.GROUPID  - Group ID, one of "syst", "text", "docu", "soun",
  2096.                           "inst", "musi", "pict", "anim", "movi"
  2097.  
  2098.         HEADER.GROUPIDNAME - Localized format of HEADER.GROUPID, (e.g.
  2099.                           "System", "Text", ...
  2100.  
  2101.         HEADER.ID       - For IFF datatypes, this is the IFF FORM code,
  2102.                           for other datatypes these are the first four
  2103.                           letters of the name field
  2104.  
  2105.         HEADER.BASETYPE - Base type, on of "binary", "ascii", "iff", "other"
  2106.  
  2107.         HEADER.BASETYPENAME - Localized format of HEADER.BASETYPE (e.g.
  2108.                           "Binary", "ASCII", "IFF", "Miscellaneous"
  2109.  
  2110.         FUNCTIONNAME    - Name of comparisation function
  2111.  
  2112.         ATTRLIST        - Stem list of datatype prefs tag items
  2113.             ATTRLIST.COUNT - Total number of attributes
  2114.  
  2115.             ATTRLIST.i.TAG - Name of tag
  2116.  
  2117.             ATTRLIST.i.DATA - Data value
  2118.  
  2119.             (Not functional without "objecttools.library".)
  2120.  
  2121.         TOOLLIST. - Tool nodes stem list, with following members
  2122.             TOOLLIST.COUNT - Total number of tool nodes in this list
  2123.  
  2124.             TOOLLIST.i.WHICH   - "Which" sort of program, one of "misc",
  2125.                 "info", "browse", "edit", "print", "mail", "undefined"
  2126.  
  2127.             TOOLLIST.i.LAUNCH  - Launch mode of tool, one of "shell",
  2128.                 "workbench", "rx", "undefined"
  2129.  
  2130.             TOOLLIST.i.PROGRAM - Full path of the tool
  2131.  
  2132.             TOOLLIST.i.FLAGS - Hex-Version of toolnodes "flags" field,
  2133.                 usage should be rare...
  2134.  
  2135.             'i' above means loop-"interator".
  2136.  
  2137.     EXAMPLE
  2138.         /* $VER: obtaindatatype.rexx 1.1 (19.5.97) */
  2139.  
  2140.         PARSE ARG fname
  2141.         OPTIONS RESULTS
  2142.  
  2143.         /* Load the datatypes.library as a function host */
  2144.         IF ~SHOW( 'L', 'datatypes.library' ) THEN
  2145.            CALL ADDLIB( 'datatypes.library', 0, -30 )
  2146.  
  2147.            IF fname="" THEN DO
  2148.               SAY "Usage:"
  2149.               SAY "  rx obtaindatatype <filename>"
  2150.               EXIT
  2151.            END
  2152.  
  2153.            SAY 'stem test'
  2154.            CALL ObtainDataType( FILE, fname, dtstem. )
  2155.  
  2156.            SAY '             Name:' dtstem.header.name
  2157.            SAY '         Basename:' dtstem.header.basename
  2158.            SAY '          Pattern:' dtstem.header.pattern
  2159.            SAY '          GroupID:' dtstem.header.groupid
  2160.            SAY '               ID:' dtstem.header.id
  2161.            SAY '         Basetype:' dtstem.header.basetype
  2162.            SAY '     Functionname:' dtstem.functionname
  2163.  
  2164.         /*  ATTRLIST not set up in V45 */
  2165.  
  2166.            DO i = 0 TO (dtstem.toollist.count - 1)
  2167.              SAY 'Tool Node ' i
  2168.              SAY '          Program:' dtstem.toollist.i.program
  2169.              SAY '            Which:' dtstem.toollist.i.which
  2170.              SAY '           Launch:' dtstem.toollist.i.launch
  2171.              SAY '            Flags:' dtstem.toollist.i.flags
  2172.            END
  2173.         EXIT
  2174.  
  2175.     NOTE
  2176.         Without objecttools.library, struct DataType -> dtn_AttrList cannot 
  2177.         be converted into STEM vars.
  2178.  
  2179.     SEE ALSO
  2180.         rexx/EXAMINEDT,
  2181.         rexx/LAUNCHTOOL
  2182.  
  2183. datatypes.library/SaveDTObjectA               datatypes.library/SaveDTObjectA
  2184.  
  2185.    NAME
  2186.         SaveDTObjectA -- Save object's contents                     (V45)
  2187.  
  2188.    SYNOPSIS
  2189.         success = SaveDTObjectA( o, win, req, file, mode, saveicon, attrs );
  2190.         d0                       a0 a1   a2   a3    d0    d1        a4
  2191.  
  2192.         SaveDTObjectA( Object *, struct Window *, struct Requester *,
  2193.                        STRPTR, ULONG, BOOL, struct TagItem * );
  2194.  
  2195.         success = SaveDTObject( o, win, req, file, mode, saveicon, tag1,
  2196.                                 ... );
  2197.  
  2198.         SaveDTObject( Object *, struct Window *, struct Requester *,
  2199.                       STRPTR, ULONG, BOOL, Tag, ... );
  2200.  
  2201.    FUNCTION
  2202.         This function saves the contents of an object into a file.
  2203.  
  2204.         The function opens the named file and saves the object's contexts
  2205.         into it (DTM_WRITE). Then it closes the file.
  2206.         If the DTM_WRITE method returns success and the saveicon option is
  2207.         TRUE, matching icon is saved.
  2208.  
  2209.         If DTM_WRITE returns 0, the file will be deleted.
  2210.  
  2211.    INPUTS
  2212.         o        - Object like returned from NewDTObjectA
  2213.  
  2214.         win      - Window the object is attached to
  2215.  
  2216.         req      - Requester the object is attached to
  2217.  
  2218.         file     - file name to save to
  2219.  
  2220.         mode     - Save mode, (RAW, IFF etc.), one of the DTWM_#? identifiers
  2221.  
  2222.         saveicon - Save icon ?
  2223.  
  2224.         attrs    - Additional attributs
  2225.  
  2226.    TAGS
  2227.         Subclass specific.
  2228.  
  2229.         For example, animation.datatype V41 recognizes ADTA_Frame (start
  2230.         frame to save) and ADTA_Frames (number of frames to save).
  2231.  
  2232.    RETURNS
  2233.         success - The return value returned by DTM_WRITE or NULL for an
  2234.                   error.
  2235.  
  2236.    BUGS
  2237.       - Does currently not delete the file on failure.
  2238.  
  2239.       - In V45.2 and before, the file was closed after the icon was
  2240.         written. This caused Workbench to show the size of the icon
  2241.         instead of the real file.
  2242.         Fixed.
  2243.  
  2244.       - Starting with V45.3, the return value of Close will be watched
  2245.         correctly and may cause failure of this function.
  2246.  
  2247.    SEE ALSO
  2248.         datatypesclass/DTM_WRITE
  2249.  
  2250. datatypes.library/SetDTAttrsA                   datatypes.library/SetDTAttrsA
  2251.  
  2252.      NAME
  2253.         SetDTAttrsA -- Set attributes for an object.             (V39)
  2254.  
  2255.      SYNOPSIS
  2256.         retval = SetDTAttrsA( o, win, req, attrs );
  2257.         d0                    a0  a1   a2  a3
  2258.  
  2259.         ULONG SetDTAttrsA( Object *, struct Window *, struct Requester *,
  2260.                            struct TagItem * );
  2261.  
  2262.         retval = SetDTAttrs( o, win, req, tag1, ... );
  2263.  
  2264.         ULONG SetDTAttrs( Object *, struct Window *, struct Requester *,
  2265.                           Tag, ... );
  2266.  
  2267.      FUNCTION
  2268.         This function is used to set the attributes of a data type
  2269.         object.
  2270.  
  2271.      INPUTS
  2272.         o     - Pointer to an object as returned by NewDTObjectA.
  2273.  
  2274.         win   - Window that the object has been added to.
  2275.  
  2276.         req   - Requester that the object has been added to (V45).
  2277.  
  2278.         attrs - Attributes to set.
  2279.  
  2280.      TAGS
  2281.         See datatypesclass/OM_SET and <datatypes/datatypesclass.h> for tags.
  2282.  
  2283.      SEE ALSO
  2284.         datatypesclass/OM_SET,
  2285.         GetDTAttrsA,
  2286.         intuition.library/SetGadgetAttrsA
  2287.  
  2288. datatypes.library/StartDragSelect           datatypes.library/StartDragSelect
  2289.  
  2290.    NAME
  2291.         StartDragSelect -- Start drag-selection                     (V45)
  2292.  
  2293.    SYNOPSIS
  2294.         success = StartDragSelect( o );
  2295.         d0                         a0
  2296.  
  2297.         ULONG StartDragSelect( Object * );
  2298.  
  2299.    FUNCTION
  2300.         This function starts drag-selection by the user (marking).
  2301.  
  2302.         This function replaces the old flag-fiddling method to
  2303.         start drag-select.
  2304.  
  2305.         The drag-select will only be started of the object supports
  2306.         DTM_SELECT, is in a window or requester and no layout-process
  2307.         is working on the object. If all conditions are good, it sets
  2308.         the DTSIF_DRAGSELECT flag and returns TRUE for success.
  2309.  
  2310.         Starting with V45.4 Resul2 (IoErr()) contains some extra info
  2311.         about the cause:
  2312.         ERROR_ACTION_NOT_KNWON -- DTM_SELECT not supported
  2313.         ERROR_OBJECT_IN_USE    -- async layout etc. peding etc.
  2314.  
  2315.    INPUTS
  2316.         o - object like returned from NewDTObjectA
  2317.  
  2318.    RETURNS
  2319.         TRUE for success, FALSE for failure
  2320.  
  2321.    SEE ALSO
  2322.  
  2323. datatypesclass/--datasheed--                     datatypesclass/--datasheed--
  2324.  
  2325.    NAME
  2326.         datatypesclass -- base class for DataTypes
  2327.  
  2328.    SUPERCLASS
  2329.         gadgetclass
  2330.  
  2331.    FUNCTION
  2332.         This class is the "base" class for all datatypes. It provides basic
  2333.         services and attributes.
  2334.  
  2335.    METHODS
  2336.         DTM_ABORTPRINT -- Abort an asyncronous print process
  2337.  
  2338.         DTM_ASYNCLAYOUT -- Layout occuring on a seperate process
  2339.  
  2340.         DTM_FRAMEBOX -- Query or set the environment an object will enter
  2341.  
  2342.         DTM_PRINT - Print objects contents
  2343.  
  2344.         DTM_PROCLAYOUT -- Layout object on application process
  2345.  
  2346.         DTM_REMOVEDTOBJECT -- Remove object from window
  2347.  
  2348.         DTM_WRITE -- Write objects contents to file
  2349.  
  2350.         GM_DOMAIN -- Obtain the min./nom./max. dimensions of an object
  2351.  
  2352.         GM_GOACTIVE -- Activate object
  2353.  
  2354.         GM_GOINACTIVE -- Deactivate object
  2355.  
  2356.         GM_HANDLEINPUT -- Handlde user input
  2357.  
  2358.         GM_HITTEST -- Check if object was hit
  2359.  
  2360.         GM_LAYOUT -- Layout object
  2361.  
  2362.         OM_DISPOSE -- Dispose object
  2363.  
  2364.         OM_GET -- Obtain the value of an attribute
  2365.  
  2366.         OM_NEW -- Create an dt object
  2367.  
  2368.         OM_SET -- Set the values of various attributes
  2369.  
  2370.         OM_UPDATE -- Update the values of various attributes
  2371.  
  2372.    ATTRIBUTES
  2373.         The following attributes are used by datatypes. Note that
  2374.         there is a difference between "Application"- and "Subclass"-
  2375.         applicability. The following list are assumptions "How the
  2376.         interface should work".
  2377.  
  2378.         /* Generic attributes */
  2379.         DTA_TextAttr (struct TextAttr *) - Pointer to the default TextAttr
  2380.             to use for the text within the object.
  2381.  
  2382.             Applicability for applications is (IG),
  2383.             Applicability for subclasses   is (SG).
  2384.  
  2385.         DTA_TopVert (LONG) - Current top vertical unit
  2386.  
  2387.             Applicability for applications is (ISG),
  2388.             Applicability for subclasses   is (SGNU).
  2389.  
  2390.         DTA_VisibleVert (LONG) - Number of visible vertical units
  2391.  
  2392.             Applicability for applications is (ISG),
  2393.             Applicability for subclasses   is (SGNU).
  2394.  
  2395.         DTA_TotalVert (LONG) - Total number of vertical units
  2396.  
  2397.             Applicability for applications is (ISG),
  2398.             Applicability for subclasses   is (SGNU).
  2399.  
  2400.         DTA_VertUnit (LONG) - Number of pixels per vertical unit
  2401.  
  2402.             Applicability for applications is (ISG),
  2403.             Applicability for subclasses   is (SGNU).
  2404.  
  2405.         DTA_TopHoriz (LONG) - Current top horizontal unit
  2406.  
  2407.             Applicability for applications is (ISG),
  2408.             Applicability for subclasses   is (SGNU).
  2409.  
  2410.         DTA_VisibleHoriz (LONG) - Number of visible horizontal units
  2411.  
  2412.             Applicability for applications is (ISG),
  2413.             Applicability for subclasses   is (SGNU).
  2414.  
  2415.         DTA_TotalHoriz (LONG) - Total number of horizontal units
  2416.  
  2417.             Applicability for applications is (ISG),
  2418.             Applicability for subclasses   is (SGNU).
  2419.  
  2420.         DTA_HorizUnit (LONG) - Number of pixels per horizontal unit
  2421.  
  2422.             Applicability for applications is (ISG),
  2423.             Applicability for subclasses   is (SGNU).
  2424.  
  2425.         DTA_NodeName (STRPTR) - Name of the current element within the 
  2426.             object.
  2427.  
  2428.             Applicability for applications is (ISG),
  2429.             Applicability for subclasses   is (SG).
  2430.  
  2431.          DTA_Title (STRPTR) - Title of the object.
  2432.  
  2433.             Applicability for applications is (),
  2434.             Applicability for subclasses   is (N).
  2435.  
  2436.          DTA_TriggerMethods (struct DTMethod *) - Pointer to a STM_END-
  2437.             terminated array of supported trigger methods.
  2438.             (Subclasses may superset to extend this array using
  2439.             CopyDTTriggerMethods).
  2440.  
  2441.             Applicability for applications is (G),
  2442.             Applicability for subclasses   is (G).
  2443.  
  2444.          DTA_Data (Object *) - Object itself.
  2445.             Starting with V45, a DTA_Data == NULL indicates that
  2446.             an object hasn't loaded all data yet (progressive loading,
  2447.             see DTA_Progressive).
  2448.             (Subclasses which implements progressive loading are forced
  2449.             to superset OM_GET to indicate with a DTA_Data == NULL
  2450.             that loading is currently in process).
  2451.  
  2452.             Applicability for applications is (G),
  2453.             Applicability for subclasses   is (G).
  2454.  
  2455.         DTA_TextFont (struct TextFont *) - Default font to use for text 
  2456.             within the object.
  2457.             (This attribute is for subclasses only. Their superclass
  2458.             (like text.datatype) will open this font and release it on 
  2459.             disposal).          
  2460.  
  2461.             Applicability for applications is (),
  2462.             Applicability for subclasses   is (G).
  2463.  
  2464.         DTA_Methods (ULONG *) - Pointer to a ~0UL terminated array of
  2465.             supported methods. (Subclasses may superset OM_GET to replace
  2466.             the array with it's extendet array (created using CopyDTMethods))
  2467.  
  2468.             Applicability for applications is (G),
  2469.             Applicability for subclasses   is (G).
  2470.  
  2471.        DTA_PrinterStatus (LONG) - Printer error message.  Error numbers are
  2472.             defined in <devices/printer.h>, PDERR_#? identifiers.
  2473.             This tag is notified from the AsyncPrintDaemon, based on the
  2474.             return value of DTM_PRINT.
  2475.  
  2476.             Applicability for applications is (),
  2477.             Applicability for subclasses   is ().
  2478.  
  2479.        DTA_PrinterProc (struct Process *) - PRIVATE !!
  2480.            Pointer to the print process.
  2481.  
  2482.        DTA_LayoutProc (struct Process *) - PRIVATE !!
  2483.            Pointer to the layout process.
  2484.  
  2485.        DTA_Busy (BOOL) - Used to turn the applications' busy pointer off
  2486.            and on.
  2487.  
  2488.             Applicability for applications is (),
  2489.             Applicability for subclasses   is (N).
  2490.  
  2491.        DTA_Sync (BOOL) - Used to indicate that new information has been
  2492.             loaded into an object. A value of 0 indicates that the object is
  2493.             still loading (DTA_Progressive == TRUE).
  2494.  
  2495.             Applicability for applications is (),
  2496.             Applicability for subclasses   is (N).
  2497.  
  2498.        DTA_BaseName (STRPTR) - The base name of the class (library).
  2499.             This tag is currently only used by datatypes.library functions,
  2500.             not by the class itself.
  2501.  
  2502.        DTA_GroupID (ULONG) - The group a datatype must belong in (one of the
  2503.             GID_#? identifiers in <datatypes/datatypes.h>).
  2504.             This tag is currently only used by datatypes.library functions,
  2505.             not by the class itself.
  2506.  
  2507.        DTA_ErrorLevel (LONG) -  Error level (one of the RETURN_#? levels
  2508.             defined in <dos/dos.h>.
  2509.  
  2510.             Applicability for applications is (),
  2511.             Applicability for subclasses   is (N).
  2512.  
  2513.        DTA_ErrorNumber (LONG) - dos.library/datatypes.library error number,
  2514.             one of the ERROR_#? identifiers defined in <dos/dos.h> or
  2515.             one of the DTERROR_#? identifiers defined in 
  2516.             <datatypes/datatypes.h>
  2517.  
  2518.             Applicability for applications is (),
  2519.             Applicability for subclasses   is (N).
  2520.  
  2521.        DTA_ErrorString (STRPTR) - Argument for datatypes.library error
  2522.             (e.g. if the error string has a %s included...).
  2523.  
  2524.             Applicability for applications is (),
  2525.             Applicability for subclasses   is (N).
  2526.  
  2527.        DTA_Conductor (STRPTR) - Specifies the name of the realtime.library
  2528.             conductor. Will be passed to realtime.library/CreatePlayerA,
  2529.             a value of ~0UL sets up a private conductor (recommned).
  2530.  
  2531.             Applicability for applications is (I),
  2532.             Applicability for subclasses   is ().
  2533.  
  2534.        DTA_ControlPanel (BOOL) - Indicate whether a control panel should be
  2535.             embedded within the object (in the animation datatype, for
  2536.             example).
  2537.  
  2538.             Applicability for applications is (IS),
  2539.             Applicability for subclasses   is ().
  2540.  
  2541.        DTA_Immediate (BOOL) - Indicate whether the object should immediately
  2542.            begin playing.
  2543.  
  2544.             Applicability for applications is (IS),
  2545.             Applicability for subclasses   is ().
  2546.  
  2547.        DTA_Repeat (BOOL) - Indicate that the object should repeat playing.
  2548.  
  2549.             Applicability for applications is (IS),
  2550.             Applicability for subclasses   is ().
  2551.  
  2552.        DTA_Progressive (BOOL) - Indicate that the object should use
  2553.             progressive loading. The datatype will send { DTA_Sync, 0UL }
  2554.             notify msgs while loading is in progress; a final
  2555.             { DTA_Sync, 1UL } indicates that loading has been finished.
  2556.             Applications have to OM_GET DTA_Data to check if loading
  2557.             has __REALLY__ been finished. If "Object" is returned
  2558.             loading is done, a NULL return value indicates that the object
  2559.             is still loading.
  2560.  
  2561.             Applicability for applications is (IS),
  2562.             Applicability for subclasses   is ().
  2563.  
  2564.         DTA_CurrentLevel (ULONG) - Notifies the filling level of the object
  2565.             when doing (progressive) loading. 0UL means 0%,
  2566.             0xFFFFFFFFUL means 100%.
  2567.  
  2568.             Applicability for applications is (),
  2569.             Applicability for subclasses   is (N).
  2570.  
  2571.         DTA_ARexxPortName (STRPTR) - Pointer to base name for ARexx port
  2572.  
  2573.             Applicability for applications is (I),
  2574.             Applicability for subclasses   is ().
  2575.  
  2576.         /* DTObject attributes */
  2577.  
  2578.         DTA_Name (STRPTR) - (File-)Name of object
  2579.  
  2580.             Applicability for applications is (IG),
  2581.             Applicability for subclasses   is (G).
  2582.  
  2583.         DTA_SourceType (ULONG) - One of the DTST_#? identifiers
  2584.  
  2585.             Applicability for applications is (IG),
  2586.             Applicability for subclasses   is (G).
  2587.  
  2588.         DTA_Handle (APTR) - Source handle. See OM_GET for the specific
  2589.             handle type (BPTR fh, struct IFFHandle *, BPTR lock).
  2590.             Note that the handle passed at OM_NEW will NOT be the same handle
  2591.             you'll get with OM_GET.
  2592.  
  2593.             Applicability for applications is (IG),
  2594.             Applicability for subclasses   is (G).
  2595.  
  2596.         DTA_DataType (struct DataType *) -- datatype for this class.
  2597.  
  2598.             Applicability for applications is (G),
  2599.             Applicability for subclasses   is (G).
  2600.  
  2601.         DTA_Domain (struct IBox *) -- Domain box of gadget in absolute
  2602.             dimensions.
  2603.  
  2604.             Applicability for applications is (G),
  2605.             Applicability for subclasses   is (G).
  2606.  
  2607.         DTA_ObjName,
  2608.         DTA_ObjAuthor,
  2609.         DTA_ObjAnnotation,
  2610.         DTA_ObjCopyright and
  2611.         DTA_ObjVersion all (STRPTR) -- The name, author etc. of the source
  2612.             data.
  2613.  
  2614.             Applicability for applications is (G),
  2615.             Applicability for subclasses   is (SG).                      
  2616.  
  2617.         DTA_ObjectID (ULONG) -- RESERVED
  2618.  
  2619.         DTA_UserData (ULONG) -- User data like GA_UserData
  2620.  
  2621.         DTA_FrameInfo (struct FrameInfo *) -- RESERVED
  2622.  
  2623.         DTA_SelectDomain (struct IBox *) -- Select area's box, in absolute
  2624.             window/requester/screen coordinates.
  2625.  
  2626.             Applicability for applications is (G),
  2627.             Applicability for subclasses   is (SG).
  2628.  
  2629.         DTA_TotalPVert (LONG) - Object's page size, in pixels
  2630.  
  2631.             Applicability for applications is (G),
  2632.             Applicability for subclasses   is (G).
  2633.  
  2634.         DTA_TotalPHoriz (LONG) - Object's page size, in pixels
  2635.  
  2636.             Applicability for applications is (G),
  2637.             Applicability for subclasses   is (G).
  2638.  
  2639.         DTA_NominalVert (LONG) - nominal height of object
  2640.  
  2641.             Applicability for applications is (G),
  2642.             Applicability for subclasses   is (SG).
  2643.  
  2644.         DTA_NominalHoriz (LONG) - nominal height of object
  2645.  
  2646.             Applicability for applications is (G),
  2647.             Applicability for subclasses   is (SG).
  2648.  
  2649.  
  2650.         /* Printing attributes */
  2651.         The printing attributes are only used in conjunction with DTM_PRINT.
  2652.  
  2653.         DTA_DestCols (LONG) - Destination X width
  2654.         DTA_DestRows (LONG) - Destination Y height
  2655.         DTA_Special (UWORD) - Option flags, see <devices/printer.h>
  2656.         DTA_RastPort (struct RastPort *) - RastPort to use when printing.
  2657.  
  2658.    NOTES
  2659.  
  2660.    SEE ALSO
  2661.  
  2662.    BUGS
  2663.  
  2664. datatypesclass/DTM_ABORTPRINT                   datatypesclass/DTM_ABORTPRINT
  2665.  
  2666.     NAME
  2667.         DTM_ABORTPRINT -- Aborts a pending print job
  2668.  
  2669.     FUNCTION
  2670.         This methods aborts a pendig print job.
  2671.  
  2672.         Note that you must wait for the print process before
  2673.         you can dispose the object. DisposeDTObject will wait until
  2674.         the job exists.
  2675.  
  2676.     RESULT
  2677.         Returns 0 for now.
  2678.  
  2679. datatypesclass/DTM_ASYNCLAYOUT                 datatypesclass/DTM_ASYNCLAYOUT
  2680.  
  2681.     NAME
  2682.         DTM_ASYNCLAYOUT -- Asyncronous layout
  2683.  
  2684.     FUNCTION
  2685.         This method offloads time intensive things like text layout or
  2686.         remapping from input.device on a sepeate process. This
  2687.         method will only be used when the "AsyncLayoutDeamon" process
  2688.         was invoked by DoAsyncLayout in the GM_LAYLOUT method.
  2689.  
  2690.     RESULT
  2691.         Non-zero for success, 0 for failure.
  2692.  
  2693.     SEE ALSO
  2694.         GM_LAYOUT,
  2695.         datatypes.library/DoAsyncLayout
  2696.  
  2697. datatypesclass/DTM_FRAMEBOX                       datatypesclass/DTM_FRAMEBOX
  2698.  
  2699.     NAME
  2700.         DTM_FRAMEBOX -- Inquire what environment an object requires
  2701.  
  2702.     FUNCTION
  2703.         This method is to inquire what environment an object requires,
  2704.         which depends on the source data; an object like a picture
  2705.         or an animation maybe requires special things like a HAM screen for 
  2706.         HAM pictures or HAM animations.
  2707.  
  2708.         If the FRAMEF_SPECIFY flag is set in the msg, the method tells
  2709.         the object to prepare itself to enter the described environment.
  2710.  
  2711.         datatypesclass does __currently__ do nothing on the FrameInfo
  2712.         structure given, but must be called when an object receives a
  2713.         DTM_FRAMEBOX method.
  2714.  
  2715.         If the DTA_SourceType attribute equals to DTST_CLIPBOARD,
  2716.         the clipboard handle will be closed here.
  2717.  
  2718.     RESULT
  2719.         Nothing returned.
  2720.  
  2721. datatypesclass/DTM_PRINT                             datatypesclass/DTM_PRINT
  2722.  
  2723.     NAME
  2724.         DTM_PRINT -- print object
  2725.  
  2726.     FUNCTION
  2727.         This method should print the contents of the object.
  2728.  
  2729.         This method should be superset by the given subclass.
  2730.         datatypesclass returns PDERR_CANCEL and sets IoErr to 
  2731.         ERROR_NOT_IMPLEMENTED.
  2732.  
  2733.     ATTRIBUTES
  2734.         A subclass may recognise one of the following attribues:
  2735.  
  2736.         DTA_DestCols (LONG) - Destination X width, see <devices/printer.h>
  2737.  
  2738.         DTA_DestRows (LONG) - Destination Y height, see <devices/printer.h>
  2739.  
  2740.         DTA_Special (UWORD) - Option flags,
  2741.             see <devices/printer.h>, SPECIAL_#? defines.
  2742.  
  2743.         DTA_RastPort (struct RastPort *) RastPort to use when printing. (V40)
  2744.             Must only be used of the datatypes object is used like
  2745.             an image (e.g. in a DTM_OBTAINDRAWINFO/DTM_DRAW/
  2746.             DTM_RELEASEDRAWINFO cycle). The rastport given should be the same
  2747.             passed to DTM_DRAW.
  2748.             This tag MUST not be used if the object is used as a gadget.
  2749.  
  2750.         Other tags are subclass-specific:
  2751.         For example, a animation.datatype (V42) subclass may recognise
  2752.  
  2753.         ADTA_Frame (ULONG) - start frame to print
  2754.  
  2755.         ADTA_Frames (ULONG) - number of frames to print.
  2756.  
  2757.         and so on.
  2758.  
  2759.     NOTE
  2760.         This method is normally asyncrony launched using PrintDTObjectA.
  2761.         The async print process will notify the return value of this
  2762.         method as DTA_PrinterStatus.
  2763.  
  2764.     RESULT
  2765.         Returns PDERR_CANCEL and (result2 == ERROR_NOT_IMPLEMENTED).
  2766.  
  2767.     SEE ALSO
  2768.         datatypes.library/PrintDTObjectA,
  2769.         <devices/printer.h>
  2770.  
  2771. datatypesclass/DTM_PROCLAYOUT                   datatypesclass/DTM_PROCLAYOUT
  2772.  
  2773.     NAME
  2774.         DTM_PROCLAYOUT -- Layout datatypesclass object
  2775.  
  2776.     FUNCTION
  2777.         This method should be treated like DTM_ASYNCLAYOUT. The only
  2778.         difference is that DTM_ASYNCLAYOUT is triggered by the
  2779.         GM_LAYOUT method, which calls the DoAsyncLayout function
  2780.         ("AsyncLayoutDeamon" process launched by it), DTM_PROCLAYOUT is
  2781.         triggered by the application manually.
  2782.  
  2783.         The DTM_PROCLAYOUT method replaces both GM_LAYOUT and DTM_ASYNCLAYOUT
  2784. .
  2785.  
  2786.         DTM_PROCLAYOUT should not be triggered when the object will be added
  2787.         into an window/requester using AddDTObject.
  2788.  
  2789.         This method is exacly the same as datatypesclass/GM_LAYOUT.
  2790.  
  2791.     RESULT
  2792.         See GM_LAYOUT
  2793.  
  2794. datatypesclass/DTM_REMOVEDTOBJECT           datatypesclass/DTM_REMOVEDTOBJECT
  2795.  
  2796.     NAME
  2797.         DTM_REMOVEDTOBJECT -- Remove a dt object from a window/requester
  2798.  
  2799.     FUNCTION
  2800.         Releases resources obtained during GM_LAYOUT/DTM_PROCLAYOUT.
  2801.  
  2802.         This method MUST be passed to datatypesclass if an object receives
  2803.         a DTM_REMOVEDTOBJECT msg.
  2804.  
  2805.     RESULT
  2806.         GM_LAYOUT, DTM_PROCLAYOUT
  2807.  
  2808. datatypesclass/DTM_WRITE                             datatypesclass/DTM_WRITE
  2809.  
  2810.     NAME
  2811.         DTM_WRITE -- Write object to file
  2812.  
  2813.     FUNCTION
  2814.         This method should write the contens of an object to a file.
  2815.  
  2816.         This method should be superset by the given subclass.
  2817.         datatypesclass returns 0 and sets IoErr to ERROR_NOT_IMPLEMENTED.
  2818.  
  2819.     ATTRIBUTES
  2820.         Class specific.
  2821.         For example, a animation.datatype subclass may recognise
  2822.  
  2823.         ADTA_Frame (ULONG) - start frame to save
  2824.  
  2825.         ADTA_Frames (ULONG) - number of frames to save.
  2826.  
  2827.         and so on.
  2828.  
  2829.     NOTE
  2830.         If a datatypesclass has the version 45 or higher, a NULL
  2831.         file handle must be a NOP. This was introduced to check if
  2832.         a particular subclass supports DTM_WRITE with DTWM_RAW (local
  2833.         format).
  2834.  
  2835.     RESULT
  2836.         Returns 0 and (result2 == ERROR_NOT_IMPLEMENTED).
  2837.  
  2838.     SEE ALSO
  2839.  
  2840. datatypesclass/GM_DOMAIN                             datatypesclass/GM_DOMAIN
  2841.  
  2842.     NAME
  2843.         GM_DOMAIN -- obtain the domain of an datatypes object (V45)
  2844.  
  2845.     FUNCTION
  2846.        The GM_DOMAIN method is used to obtain the domain of a
  2847.        datatypesclass object. datatypesclass requires an object
  2848.        to process this method.
  2849.  
  2850.        Subclasses may require a RastPort pointer in gpd_RPort with the
  2851.        correct font attributes.
  2852.  
  2853.        datatypesclass supports the gpd_Which == GDOMAIN_MINIMUM,
  2854.        GDOMAIN_NOMINAL and GDOMAIN_MAXIMUM.
  2855.  
  2856.        If the gpd_GInfo (GadgetInfo) is valid (non-NULL), the
  2857.        (gpd_Domain . Left) and (gpd_Domain . Top) fields will be filled based
  2858.        on the values set with GA_Left/GA_Top/GA_RelRight/GA_RelBottom.
  2859.        otherwise these two fields are 0 as noted below.
  2860.  
  2861.        If all attributes got are 0, GDOMAIN_NOMINAL and GDOMAIN_MAXIMUM
  2862.        fall back to width=600, height=200. This fallback dimensions may vary
  2863.        from case to case.
  2864.  
  2865.        GDOMAIN_MINIMUM returns 0,0,0,0
  2866.  
  2867.        GDOMAIN_NOMINAL returns 0,0,DTA_NominalHoriz,DTA_NominalVert
  2868.            If the DTA_NominalHoriz is 0,
  2869.            (DTA_TotalHoriz * MAX( DTA_HorizUnit, 1 )) is used instead.
  2870.            If the DTA_NominalVert is 0,
  2871.            (DTA_TotalVert * MAX( DTA_VertUnit, 1 )) is used instead.
  2872.  
  2873.        GDOMAIN_MAXIMUM returns 0,0,
  2874.            (DTA_TotalHoriz * MAX( DTA_HorizUnit, 1 )),
  2875.            (DTA_TotalVert * MAX( DTA_VertUnit, 1 )).
  2876.  
  2877.     ATTRIBUTES
  2878.        datatypesclass does ignore any args, but subclasses may depend on
  2879.        some of these tags:
  2880.  
  2881.        DTA_TextAttr (struct TextAttr *) - Default text font used in object
  2882.  
  2883.     NOTE
  2884.        Subclasses may superset some of the GDOMAIN_#? cases above,
  2885.        but MUST pass unknown or unsupported cases to datatypesclass.
  2886.  
  2887.     TODO
  2888.        Replace the hard-coded fallback domain (w=600, h=200) with
  2889.        an more smarter way...
  2890.  
  2891.     RESULT
  2892.        Returns TRUE and fills in the gpd_Domain field if successfull,
  2893.        FALSE otherwise.
  2894.  
  2895.     SEE ALSO
  2896.        datatypes.library/DoDTDomain
  2897.  
  2898.  
  2899. datatypesclass/GM_GOACTIVE                         datatypesclass/GM_GOACTIVE
  2900.  
  2901.     NAME
  2902.         GM_GOACTIVE -- prepare the object to be activated
  2903.  
  2904.     FUNCTION
  2905.         Prepare the object to be activated.
  2906.         This method falls through to GM_HANDLEINPUT
  2907.  
  2908.     RESULT
  2909.         See GM_HANDLEINPUT
  2910.  
  2911. datatypesclass/GM_GOINACTIVE                     datatypesclass/GM_GOINACTIVE
  2912.  
  2913.     NAME
  2914.         GM_GOINACTIVE -- Deactivate object
  2915.  
  2916.     FUNCTION
  2917.  
  2918.     RESULT
  2919.  
  2920. datatypesclass/GM_HANDLEINPUT                   datatypesclass/GM_HANDLEINPUT
  2921.  
  2922.     NAME
  2923.         GM_HANDLEINPUT -- handle input
  2924.  
  2925.     FUNCTION
  2926.  
  2927.     RESULT
  2928.  
  2929. datatypesclass/GM_HITTEST                           datatypesclass/GM_HITTEST
  2930.  
  2931.     NAME
  2932.         GM_HITTEST -- Test if the object has been hit
  2933.  
  2934.     FUNCTION
  2935.         The GM_HITTEST queries the object if the given coordinates hits
  2936.         the datatypesclass object.
  2937.  
  2938.     RESULT
  2939.         Returns evertimes GMR_GADGETHIT.
  2940.  
  2941. datatypesclass/GM_LAYOUT                             datatypesclass/GM_LAYOUT
  2942.  
  2943.     NAME
  2944.         GM_LAYOUT -- Layout datatypesclass object
  2945.  
  2946.     FUNCTION
  2947.         Layout datatypesclass object.
  2948.  
  2949.         This method updates the DTA_Domain box to reflect the absolute
  2950.         dimensions of the gadget's domain box and updates the DTA_TotalPVert
  2951.         and DTA_TotalPHoriz attributes.
  2952.  
  2953.         Gadget relativity is fully supported.
  2954.  
  2955.         After all this method falls througth to the DTM_FRAMEBOX method.
  2956.  
  2957.     RESULT
  2958.  
  2959. datatypesclass/OM_DISPOSE                           datatypesclass/OM_DISPOSE
  2960.  
  2961.     NAME
  2962.         OM_DISPOSE -- Dispose datatypesclass instance
  2963.  
  2964.     FUNCTION
  2965.         This method destroys a datatypesclass object, freeing all resources
  2966.         obtained by it.
  2967.  
  2968.         This method preserves the IoErr error value.
  2969.  
  2970.     RESULT
  2971.         Returns the return code from superclass.
  2972.  
  2973. datatypesclass/OM_GET                                   datatypesclass/OM_GET
  2974.  
  2975.     NAME
  2976.         OM_GET -- Get a datatypesclass attribute
  2977.  
  2978.     FUNCTION
  2979.         The OM_GET method is used to obtain the value of a datatypesclass
  2980.         attribute.
  2981.         If the attribute to get not recognizes by datatypesclass, the msg
  2982.         is passes to superclass (gadgetclass).
  2983.  
  2984.     ATTRIBUTES
  2985.         DTA_TopVert (LONG) - Returns (dtsi -> si_TopVert)
  2986.  
  2987.         DTA_VisibleVert (LONG) - Returns (dtsi -> si_VisVert)
  2988.  
  2989.         DTA_TotalVert (LONG) - Returns (dtsi -> si_TotVert)
  2990.  
  2991.         DTA_VertUnit (LONG) - Returns (dtsi -> si_VertUnit)
  2992.  
  2993.         DTA_TopHoriz (LONG) - Returns (dtsi -> si_TopHoriz)
  2994.  
  2995.         DTA_VisibleHoriz (LONG) - Returns (dtsi -> si_VisHoriz)
  2996.  
  2997.         DTA_TotalHoriz (LONG) - Returns (dtsi -> si_TotHoriz)
  2998.  
  2999.         DTA_HorizUnit (LONG) - Returns (dtsi -> si_HorizUnit)
  3000.  
  3001.         DTA_PrinterProc (struct Process *) - PRIVATE !
  3002.  
  3003.         DTA_LayoutProc (struct Process *) - PRIVATE !
  3004.  
  3005.         DTA_Name (STRPTR) - File name set in OM_NEW
  3006.  
  3007.         DTA_SourceType (ULONG) - Source handle type of DTA_Handle,
  3008.             one of the DTST_#? identifies.
  3009.  
  3010.         DTA_Handle (APTR) - Handle, as opened by datatypesclass/OM_NEW
  3011.             The following table shows the type of handle returned
  3012.             (the "DTF_ type"-column below means which type (DTF_BINARY,
  3013.             DTF_ASCII, DTF_IFF or DTF_MISC your datatype belongs to; e.g. an
  3014.             IFF datatype will only get IFF Handles etc.):
  3015.  
  3016.             DTA_SourceType|DTF_ type |Handle type
  3017.             ================================================================
  3018.             DTST_RAM      |DTF_#?    |--      Must be NULL.
  3019.             --------------+----------+--------------------------------------
  3020.             DTST_FILE     |DTF_BINARY|(BPTR), like returned from Open
  3021.                           |DTF_ASCII |(BPTR), like returned from Open
  3022.                           |DTF_IFF   |(struct IFFHandle *), iffparse.library
  3023.                           |          |        handle
  3024.                           |DTF_MISC  |(BPTR), like returned from Lock
  3025.             --------------+----------+--------------------------------------
  3026.             DTST_CLIPBOARD|DTF_IFF   |(struct IFFHandle *), iffparse.library
  3027.                           |          |        handle
  3028.             --------------+----------+--------------------------------------
  3029.             DTST_HOTLINK  |DTF_#?    |NOT IMPLEMENTED YET
  3030.             --------------+----------+--------------------------------------
  3031.  
  3032.         DTA_DataType (struct DataType *) - Returns DataType structure.
  3033.             May be NULL !
  3034.  
  3035.         DTA_Domain (struct IBox *) - Returns ptr to struct IBox.
  3036.             This is equal to the GA_Left/GA_Top/GA_Width/GA_Height box,
  3037.             translated into window/requester coordinates, even if the
  3038.             GA_#? identifers are relative (GA_Rel#?).
  3039.  
  3040.         DTA_ObjName (STRPTR) - Source data name
  3041.  
  3042.         DTA_ObjAuthor (STRPTR) - Source data author
  3043.  
  3044.         DTA_ObjAnnotatiom (STRPTR) - Source data annotation
  3045.  
  3046.         DTA_ObjCopyright (STRPTR) - Source data copyright
  3047.  
  3048.         DTA_ObjVersion (STRPTR) - Source data version
  3049.  
  3050.         DTA_ObjectID (ULONG) - Object ID
  3051.  
  3052.         DTA_UserData (ULONG) - User data, not touched by datatypesclass
  3053.             or a subclass (like GA_UserData).
  3054.  
  3055.         DTA_FrameInfo - (struct FrameInfo *)
  3056.  
  3057.         DTA_SelectDomain (struct IBox *) - Box of selected area in
  3058.             window/requester coordinates. Returns NULL is there is
  3059.             no selected area.
  3060.  
  3061.         DTA_TotalPVert (LONG) - Page height, e.g.
  3062.             ((dtsi -> si_VertUnit) * (dtsi -> si_TotVert)) or
  3063.             (DTA_Domain . Height) if VertUnit is 0.
  3064.  
  3065.         DTA_TotalPHoriz (LONG) - Page width, e.g.
  3066.             ((dtsi -> si_HorizUnit) * (dtsi -> si_TotHoriz)) or
  3067.             (DTA_Domain . Width) if HorizUnit is 0.
  3068.  
  3069.         DTA_NominalVert (LONG) - Nominal object height.
  3070.  
  3071.         DTA_NominalHoriz (LONG) - Nominal object width.
  3072.  
  3073.         DTA_Data (Object *) - The object itself (V45).
  3074.             A NULL return indicates that the object hasn't loaded
  3075.             all data yet (progressive loading, see DTA_Progressive).
  3076.             (a subclass has to superset OM_GET to set this tag
  3077.             to NULL, datatypesclass will everytimes return the "Object"
  3078.             itself).
  3079.  
  3080.     BUGS
  3081.         None known.
  3082.  
  3083.     RESULT
  3084.         Returns TRUE if the datatypesclass supports this attribute,
  3085.         returns the superclass (gadgetclass) return value otherwise.
  3086.  
  3087. datatypesclass/OM_NEW                                   datatypesclass/OM_NEW
  3088.  
  3089.     NAME
  3090.         OM_NEW -- Create a datatypesclass object.
  3091.  
  3092.     FUNCTION
  3093.         The OM_NEW method is used to create an instance of the datatypesclass
  3094.         class.  This method is passed to the superclass first.
  3095.  
  3096.         After this, datatypesclass opens a handle. The type of handle
  3097.         will be selected based on type of input data the class can process
  3098.         (e.g. an IFF DataType will get only IFFHandles, to make things
  3099.         easier).
  3100.  
  3101.         This class cannot be create objects without having a subclass
  3102.         ("abstract" class). Starting with V45, any attempt to create a
  3103.         object of datatypesclass will be rejected by this method; only
  3104.         object's of one of it's subclasses are allowed.
  3105.  
  3106.         The following table shows the type of handle returned (the
  3107.         "DTF_ type"-column below means which type (DTF_BINARY, DTF_ASCII,
  3108.         DTF_IFF or DTF_MISC your datatype belongs to)
  3109.         (the handle must be obtained using GetDTAttrsA):
  3110.  
  3111.         DTA_SourceType|DTF_ type |Handle type
  3112.         ================================================================
  3113.         DTST_RAM      |DTF_#?    |--      Must be NULL.
  3114.         --------------+----------+--------------------------------------
  3115.         DTST_FILE     |DTF_BINARY|(BPTR), like returned from Open
  3116.                       |DTF_ASCII |(BPTR), like returned from Open
  3117.                       |DTF_IFF   |(struct IFFHandle *), iffparse.library
  3118.                       |          |        handle
  3119.                       |DTF_MISC  |(BPTR), like returned from Lock
  3120.         --------------+----------+--------------------------------------
  3121.         DTST_CLIPBOARD|DTF_IFF   |(struct IFFHandle *), iffparse.library
  3122.                       |          |        handle
  3123.         --------------+----------+--------------------------------------
  3124.         DTST_HOTLINK  |DTF_#?    |NOT IMPLEMENTED YET
  3125.         --------------+----------+--------------------------------------
  3126.  
  3127.  
  3128.     ATTRIBUTES
  3129.         The following attributes can be specified at creation time:
  3130.  
  3131.     BUGS
  3132.  
  3133.     RESULT
  3134.         If the object was created a pointer to the object is returned,
  3135.         otherwise NULL is returned.
  3136.  
  3137. datatypesclass/OM_SET                                   datatypesclass/OM_SET
  3138.  
  3139.     NAME
  3140.         OM_SET -- Set datatypesclass attributes
  3141.  
  3142.     FUNCTION
  3143.         The OM_SET method is used to set datatypesclass attributes.
  3144.  
  3145.         Does bounds checking on the DTSpecialInfo's fields si_TopVert,
  3146.         si_VisVert, si_TotVert, si_TopHoriz, si_VisHoriz and si_TotHoriz
  3147.         and notifies changes.
  3148.  
  3149.     ATTRIBUTES
  3150.         DTA_TopVert (LONG) - current vertical position.
  3151.             Copied into (dtsi -> si_TopVert); this method returns TRUE for
  3152.             a value change.
  3153.  
  3154.         DTA_VisibleVert (LONG) - visible area
  3155.             Copied into (dtsi -> si_VisVert); this method returns TRUE for
  3156.             a value change.
  3157.  
  3158.         DTA_TotalVert (LONG) - total vertical size
  3159.             Copied into (dtsi -> si_TotVert); this method returns TRUE for
  3160.             a value change.
  3161.  
  3162.         DTA_VertUnit (LONG) - vertical unit
  3163.             Size of one unit in which the DTA_(Top|Visible|Total)Vert
  3164.             attributes counts.
  3165.  
  3166.         DTA_TopHoriz (LONG) - current horizontal position.
  3167.             Copied into (dtsi -> si_TopHoriz); this method returns TRUE for
  3168.             a value change.
  3169.  
  3170.         DTA_VisibleHoriz (LONG) - visible area
  3171.             Copied into (dtsi -> si_VisHoriz); this method returns TRUE for
  3172.             a value change.
  3173.  
  3174.         DTA_TotalHoriz (LONG) - total horizontal size
  3175.             Copied into (dtsi -> si_TotHoriz); this method returns TRUE for
  3176.             a value change.
  3177.  
  3178.         DTA_HorizUnit (LONG) - horizontal unit
  3179.             Size of one unit in which the DTA_(Top|Visible|Total)Horiz
  3180.             attributes counts.
  3181.  
  3182.         DTA_PrinterProc (struct Process *) -- PRIVATE !
  3183.  
  3184.         DTA_LayoutProc (struct Process *) -- PRIVATE !
  3185.  
  3186.         DTA_ObjName (STRPTR) - name of object source data
  3187.             The string given will be copied into an internal buffer.
  3188.  
  3189.         DTA_ObjAuthor (STRPTR) - source data author
  3190.             The string given will be copied into an internal buffer.
  3191.  
  3192.         DTA_ObjAnnotation (STRPTR) - source data annotation
  3193.             The string given will be copied into an internal buffer.
  3194.  
  3195.         DTA_ObjCopyright (STRPTR) - source data copyright
  3196.             The string given will be copied into an internal buffer.
  3197.  
  3198.         DTA_ObjVersion (STRPTR) - source data copyright
  3199.             The string given will be copied into an internal buffer.
  3200.  
  3201.         DTA_ObjectID (ULONG) - object id
  3202.  
  3203.         DTA_UserData (ULONG) - User data, not touched by datatypesclass
  3204.             or a subclass (like GA_UserData).
  3205.  
  3206.         DTA_SelectDomain (struct IBox *) - selected area box,
  3207.             in window/requester coordinates.
  3208.             NULL is a valid input (V45).
  3209.  
  3210.         DTA_NominalVert (LONG) - nominal vertical size (height)
  3211.  
  3212.         DTA_NominalHoriz (LONG) - nominal vertical size (width)
  3213.  
  3214.     BUGS
  3215.         None kown.
  3216.  
  3217.     TODO
  3218.         Changes of the GA_Left/GA_Top/GA_Width/GA_Height
  3219.  
  3220.     RESULT
  3221.         If any of the DTA_(Top|Visbible|Total)(Vert|Horiz)-attributes
  3222.         has been changes, this method returns non-zero (change),
  3223.         the return value from superclass (gadgetclass) otherwise.
  3224.  
  3225. datatypesclass/OM_UPDATE                             datatypesclass/OM_UPDATE
  3226.  
  3227.     NAME
  3228.         OM_UPDATE -- Update datatypesclass attributes
  3229.  
  3230.     FUNCTION
  3231.         The OM_UPDATE method is used to update datatypesclass attributes;
  3232.         it falls througth to OM_SET.
  3233.  
  3234.         Starting with V45, OM_UPDATE will explicitly call ICM_CHECKLOOP
  3235.         to avoid notify loops.
  3236.  
  3237.     ATTRIBUTES
  3238.         See OM_SET
  3239.  
  3240.     RESULT
  3241.         See OM_SET
  3242.  
  3243.