home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
telefisk.org
/
virusCollection.lzx
/
VirusResearch
/
DataType-trojan
/
arcs
/
datatypes.library.doc
< prev
next >
Wrap
Text File
|
2012-08-06
|
109KB
|
3,243 lines
TABLE OF CONTENTS
datatypes.library/--background--
datatypes.library/--history--
datatypes.library/--V45_release--
datatypes.library/AddDTObject
datatypes.library/CopyDTMethods
datatypes.library/CopyDTTriggerMethods
datatypes.library/DisposeDTObject
datatypes.library/DoAsyncLayout
datatypes.library/DoDTDomainA
datatypes.library/DoDTMethodA
datatypes.library/DrawDTObjectA
datatypes.library/FindMethod
datatypes.library/FindToolNodeA
datatypes.library/FindTriggerMethod
datatypes.library/FreeDTMethods
datatypes.library/GetDTAttrsA
datatypes.library/GetDTMethods
datatypes.library/GetDTString
datatypes.library/GetDTTriggerMethodDataFlags
datatypes.library/GetDTTriggerMethods
datatypes.library/LaunchToolA
datatypes.library/LockDataType
datatypes.library/NewDTObjectA
datatypes.library/ObtainDataTypeA
datatypes.library/ObtainDTDrawInfoA
datatypes.library/PrintDTObjectA
datatypes.library/RefreshDTObjectA
datatypes.library/ReleaseDataType
datatypes.library/ReleaseDTDrawInfo
datatypes.library/RemoveDTObject
datatypes.library/rexx/--rexxhost--
datatypes.library/rexx/EXAMINEDT
datatypes.library/rexx/FINDTOOL
datatypes.library/rexx/GETDTSTRING
datatypes.library/rexx/LAUNCHTOOL
datatypes.library/rexx/OBTAINDATATYPE
datatypes.library/SaveDTObjectA
datatypes.library/SetDTAttrsA
datatypes.library/StartDragSelect
datatypesclass/--datasheed--
datatypesclass/DTM_ABORTPRINT
datatypesclass/DTM_ASYNCLAYOUT
datatypesclass/DTM_FRAMEBOX
datatypesclass/DTM_PRINT
datatypesclass/DTM_PROCLAYOUT
datatypesclass/DTM_REMOVEDTOBJECT
datatypesclass/DTM_WRITE
datatypesclass/GM_DOMAIN
datatypesclass/GM_GOACTIVE
datatypesclass/GM_GOINACTIVE
datatypesclass/GM_HANDLEINPUT
datatypesclass/GM_HITTEST
datatypesclass/GM_LAYOUT
datatypesclass/OM_DISPOSE
datatypesclass/OM_GET
datatypesclass/OM_NEW
datatypesclass/OM_SET
datatypesclass/OM_UPDATE
datatypes.library/--background-- datatypes.library/--background--
PURPOSE
The datatypes.library provides transparent data handling
abilities to applications. Application developers can register
their data format with datatypes.library and provide a class
library for handling their data within other applications.
OVERVIEW
* Object Oriented
datatypes.library implementation is object oriented, using the
boopsi functions of Intuition. Each data class is implemented
as a shared system library.
* Embedded Objects
datatypes.library provides the ability to embed different object
types within an application. For example, an application can
embed an picture object or even an AmigaGuide document browser
within their application's window. Objects can also be embedded
within other objects.
See Examples/embed_datatype/
* Gadget-like
Embedded objects are actually boopsi gadgets. That means that
input handling is done on Intuition's task. Time intensive
operations, such as layout when the window size changes, are
off-loaded to a sub-process. Printing, clipboard operations,
file read/write are also off-loaded to a separate process on an
as-needed basis.
See Examples/DTRequester/DTRequester.c
* Image-like
Embedded objects can also be treated as boopsi images.
For example, an application can draw an image into the background
of it's GUI, without fiddling with any internals of the object.
See Examples/DTImage/DTImage.c
* Trigger Methods
Sometimes it is necessary for an application to provide
additional controls for navigating through an object. For
example, with an AmigaGuide object it is necessary to have
controls for "Contents", "Index", "Browse >", "Browse <". Each
class implements a method that returns the trigger methods, and
the appropriate labels, that a class supports. Options can
also provided to those trigger methods.
See Examples/DTRequester/DTRequester.c
* Format Conversion
As long as the objects are sub-classes of the same class, data
from one format can be written out as another format. For
example, it is possible to read in an ILBM file and write out a
JPEG file, since both data types are sub-classes of PICTURE.
See Examples/DTConvert/DTConvert.c
* Future Compatible
Each class implements a method that returns the supported
methods within a class. This way an application can ask an
object if it is capable of any particular method, such as
DTM_WRITE for example.
* Data Type Detection
datatypes.library provides the ability to examine a file or
the clipboard to determine what type of data it contains.
See Examples/DoDT/DoDT.c and
Examples/DTDescrlist/DTDescrlist.c
* "Supported Tools"
datatypes.library maintains lists (for each data type) of
applications which supports this special datatype for their
actions (browse, edit, info, print, mail etc.).
These tools can be launched from within datatypes.library.
This lists can be edited using AddDataTypes (AddDataTypes edit).
See Examples/DoDT/DoDT.c and
Examples/DTDescrlist/DTDescrlist.c
datatypes.library/--history-- datatypes.library/--history--
V45.4
- Recompiled with SAS/C 6.58.
This may fix mc68060 related problems (I was searching for this
mc68060 incompatibility a long time :-(( ).
- Fixed a bug in LaunchToolA that the given strings were not
freed on some conditions.
Fixed.
- Fixed a bug (race condition) in RemoveDTObject that
DTM_REMOVEDTOBJECT was executed BEFORE internal RemoveGadget.
Now DTM_REMOVEDTOBJECT is correctly executed AFTER RemoveGadget.
- Internal Delay's (when waiting for flags in RemoveDTObject and
DisposeDTObject etc.)
have been reduced from 1/2 sec down to 1/5 sec.
- StartDragSelect now sets Result2 (IoErr()) with valid return
codes.
- All library calls to datatypes.library are now going througth
the LVO explicitly.
- ObtainDataTypeA has been rewritten to get more speed.
This fixes also some bugs, see below.
- ObtainDataTypeA: Fixed the bug that a 0 in the comparisation mask
was treated as an empty mask field.
Now the 0 is correctly recognized.
This fixes the bug with the QRT descriptor and some other formats.
Fixed.
- ObtainDataTypeA: Endless loop in conjunction with "PostScript"
descriptors and "DTDescrList". Problem was that the code to get
the next node from a given node didn't expect that two nodes
have the same name.
Fixed.
- ObtainDataTypeA: Fixed the memory loss of n * 40 bytes (e.g.
loss of a iffparse.library IFFHandle).
Thanks to Oliver Robers (oliver@poboxes.com) for reporting the bug.
Fixed.
- ObtainDataTypeA: Fixed a bug that an custom compatisation hook
(e.g. the DTCD code in a descriptor) for IFF forats gets an
IFFHandle and a file handle. Now only the IFFHandle is given, the
file handle is NULL (because iffparse.library manages the file
handle).
Fixed.
- ObtainDataTypeA: The clipboard did not work with masks longer
than 64 bytes.
Fixed.
- Increased the stack size of the async layout process from 8192
up to 16384 bytes. Should be __really__ enougth now.
- Changed the behaviour of DoAsyncLayout:
Previously, the DTSIF_LAYOUT flag was used to indicate that a
layout process is running.
Now the DTA_LayoutProc attribute is always checked.
The "normal" Forbid / Permit protection of async layout process
creation / signalling / deletion has been replaced by an
internal datatypes.library semaphore.
- Increased the stack size of the printer process. Should be
__really__ enougth now.
datatypes.library/--V45_release-- datatypes.library/--V45_release--
MISC
The datatypes.library V45 has been written to replace the old
datatypes.library V40.6
It introduces some interesting new features, fixes some
inconsistensies and sets more strictly rules when using
objects.
FEATURES
- The new datatypes.library V45 supports "tools", which are attached
to each datatype. Those user-defined tools are defined to handle
the datatype, an application which uses datatypes is now able to
select such a tool, search for it and launch it.
- DataTypes objects can reside inside a intuition requester.
- Supports GM_DOMAIN, which allows to include a datatypes object
in environments which uses dynamic layout (like MUI, for example).
- Implements and describes DTM_OBTAINDRAWINFO/DTM_DRAW/
DTM_RELEASEDRAWINFO, which allows usage of a datatypes object as
an image.
- V45 defines an interface for progressive loading (like GIF
pictures or SGML/HTML texts).
- Added some usefull interfaces, such as SaveDTObjectA (DTM_WRITE)
or StartDragSelect (marking).
RULES
The following list has not been completet yet...
The new datatypes.library is fully backwards compatible to V40.6,
but adds new features, and will rely on them if a datatype class
has a version equal or higher than V45.
- All subclasses must use a ClassLibrary structure.
from <intuition/classes.h>, V40.0
-- snip --
struct ClassLibrary
{
struct Library cl_Lib; /* Embedded library */
UWORD cl_Pad; /* Align the structure */
Class *cl_Class; /* Class pointer */
};
-- snip --
This was intruduced to support GM_DOMAIN and other methods
which does not require an object, and to be consistent
with other boopsi classes which should have also this interface.
- All subclasses have to support requesters. I've included
a small example which explains the usage, see
"Examples/dtrequester/dtrequester.c".
Currently, only picture.datatype V42.1, sound.datatype
and animation.datatype V41 supports this correctly.
- A DTM_WRITE method with a NULL file handle must be a NOP, but
returning correct return codes in Resul2 (IoErr).
This was introduced to check if a particular subclass supports
DTM_WRITE with DTWM_RAW (local format).
- V45 introduces an "Application" and a "Subclass" interface.
This means that the applicability of attributes for applications
and subclasses are different.
For example, the DTA_ObjName is (ISGU) for subclasses, and
(G) for applications.
(The only exception of this is if an application creates an object
with DTST_RAM. This application will be allowed to act like a
subclass).
- Objects must be able to be added to a window as a gadget
(AddDTObject), beeing removed from it (RemoveDTObject), added again
an another window in another screen. This must be repeatable
in any number (see Examples/Examples/DTRequester.c, '+' and '-'
keyboard shortcuts).
- If a datatypes class is not designed to support sub-classes, the
OM_NEW method MUST reject such an attempt (ERROR_NOT_IMPLEMENTED).
The following statement handels such a case:
/* This must not be a subclass of embed.datatype
* (not implemented nor supported)
*/
if( o == (Object *)cl )
{
/* Ok ! */
}
else
{
/* Subclasses of embed.datatype are not supported */
SetIoErr( ERROR_NOT_IMPLEMENTED );
}
- Check your inputs. Maybe, an application tries to feed a datatype
object with rubbish.
A common mistake the datatype classes have today is the missing
check if the datatype supports the given input handle type (e.g.
the DTA_SourceType attribute).
The following code shows the correct check for this (checked
inside OM_NEW):
-- snip --
/* We only support DTST_FILE as source type */
if( ti = FindTagItem( DTA_SourceType,
(((struct opSet *)msg) -> ops_AttrList) ) )
{
if( (ti -> ti_Data) != DTST_FILE )
{
SetIoErr( ERROR_NOT_IMPLEMENTED );
break;
}
}
-- snip --
Note: The DTA_SourceType attribute is examined from the OM_NEW
msg (ops_AttrList). You __MUST__ not examine DTA_Handle in such a
way.
The DTA_Handle is set up by datatypesclass ONLY, and noone else.
See OM_GET/DTA_Handle for further explanations.
- Each datatype should be shipped with an autodoc, which contains
(at least) the following entries:
--datatsheed-- Short summary of the datatype
--input_format-- Description how the input format looks like
OM_NEW What attributes does the datatype recognize ?
OM_SET/OM_UPDATE Attributes to set/update etc.
and so on.
TODO
- Add a general, flexible preferences scheme.
datatypes.library/AddDTObject datatypes.library/AddDTObject
NAME
AddDTObject -- Add an object to a window or requester. (V39)
SYNOPSIS
realposition = AddDTObject( window, requester, object, position );
d0 a0 a1 a2 d0
LONG AddDTObject( struct Window *, struct Requester *,
Object *, LONG );
FUNCTION
This function adds a single object to the gadget list of the given
window or requester at the position in the list specified by the
position argument.
When the object is added to the gadget list, the object will
receive a GM_LAYOUT message with the gpl_Initial field set to
one.
If a requester is specified, this function will set the
GTYP_REQGADGET flag.
INPUTS
window - Pointer to the window.
A NULL arg is NOP (V45).
requester - Pointer to the requester (V45)
object - Pointer to an object as returned by NewDTObjectA.
A NULL arg is NOP (V45).
position - Integer position in the list for the new gadget.
-1 to add to the end of the list.
RETURNS
Returns the position of where the object was actually added.
NOTE
Since V45, DataTypes objects can be added to requesters, too.
But you can only rely on this feature if the datatype itself
has the version V45. A requester in which a datatype resides
must not be closed before the datatype got a DTM_REMOVEDTOBJECT msg,
must not be a DM Requester nor have a GACT_ENGADGET gadget.
Note that this function __MUST__ not be uses when a datatype
object is embedded within another BOOPSI gadget. The
parent object is responsible to pass all required methods
including initial GM_LAYOUT and DTM_REMOVEDTOBJECT to
the embedded object.
BUGS
If a requester was specified, GM_LAYOUT is send manually
by this function (intuition.library didn't send a GM_LAYOUT,
OS bug ??).
SEE ALSO
RemoveDTObject,
intuition.library/AddGList
datatypes.library/CopyDTMethods datatypes.library/CopyDTMethods
NAME
CopyDTMethods -- Clone and modify DTA_Methods array (V45)
SYNOPSIS
newmethods = CopyDTMethods( methods, include, exclude );
a0 a1 a2
ULONG *CopyDTMethods( ULONG *, ULONG *, ULONG * );
FUNCTION
Copy and modify array of supported methods.
This function is used for subclass implementors, who want to
add their methods (like DTM_TRIGGER) to the array of supported
methods.
INPUTS
methods - Methods array, as obtained by GetDTMethods or DTA_Methods.
NULL causes the function to return NULL.
include - Methods to include, ~0UL terminated. May be NULL.
exclude - Methods to exclude, ~0UL terminated. May be NULL.
RESULT
newmethods - New array of methods or NULL (no memory).
BUGS
Methods to exclude will simply be overwritten by OM_NEW.
This is not really a bug, since OM_NEW should appear in any
DTA_Methods array.
SEE ALSO
FindMethod,
CopyDTTriggerMethods,
FreeDTMethods
datatypes.library/CopyDTTriggerMethods datatypes.library/CopyDTTriggerMethods
NAME
CopyDTTriggerMethods -- Clone and modify DTA_TriggerMethods array
(V45)
SYNOPSIS
newmethods = CopyDTTriggerMethods( methods, include, exclude );
a0 a1 a2
struct DTMethod *CopyDTTriggerMethods( struct DTMethod *,
struct DTMethod *,
struct DTMethod * );
FUNCTION
Copy and modify a DTMethods array.
This function is for subclass implementors for an easy way to
add their trigger methods to exising ones, or disable some because
they're internally used.
INPUTS
methods - Methods array, as obtained by GetDTTriggerMethods or
DTA_TriggerMethods.
NULL causes the function to return NULL.
include - Trigger methods to include. May be NULL.
exclude - Trigger methods to exclude. May be NULL.
The dtm_Command and dtm_Method fields may have
the options described in FindTriggerMethod to
filter/match out the given entries.
NOTE
It is assumed that the dtm_Label and dtm_Command strings are
valid as long as the object exists. They are NOT copied.
Subclasses which implements DTM_TRIGGER __MUST__ send unknown
trigger methods to it's superclass.
RESULT
newmethods - New array of methods or NULL (no memory).
SEE ALSO
FindTriggerMethod,
CopyDTMethods,
FreeDTMethods
datatypes.library/DisposeDTObject datatypes.library/DisposeDTObject
NAME
DisposeDTObject -- Delete a data type object. (V39)
SYNOPSIS
DisposeDTObject( o );
a0
VOID DisposeDTObject( Object * );
FUNCTION
This function is used to dispose of a data type object that was
obtained with NewDTObjectA. The shared class library which
was opened at NewDTObjectA time will also be closed.
This function will wait for an outstanding print or layout process.
INPUTS
o - Pointer to an object as returned by NewDTObjectA.
NULL is a valid input.
NOTE
Be sure that the boopsi class struct IClass member cl_UserData points
to the shared library class base.
SEE ALSO
NewDTObjectA,
intuition.library/DisposeObject,
datatypesclass/OM_DISPOSE
datatypes.library/DoAsyncLayout datatypes.library/DoAsyncLayout
NAME
DoAsyncLayout -- Call the DTM_ASYNCLAYOUT method on a separate
process. (V39)
SYNOPSIS
retval = DoAsyncLayout( object, gpl );
d0 a0 a1
ULONG DoAsyncLayout( Object *, struct gpLayout * );
FUNCTION
This function is used to asyncronously perform the object's
DTM_ASYNCLAYOUT method. This is used to offload the layout method
from input.device.
The DTM_ASYNCLAYOUT method must exit when SIGBREAKF_CTRL_C signal
is set. This indicates that the data has become obsolete and
the DTM_ASYNCLAYOUT method will be called again.
Starting with V45, the stack size increases from 4096 up to 8192
bytes.
INPUTS
object - Pointer to the data types object.
gpl - Pointer to a gpLayout message.
RETURNS
TRUE for success, FALSE for failure
NOTE
- Note that the "AsyncDTLayoutDaemon" process obtains the
DTSpecialInfo semaphore exclusively before triggering the
DTM_ASYNCLAYOUT method. It will be released immediately when the
method is done.
- When a layout deamon process is started, this function send a
notify msg with { DTA_Data, NULL }. This msg indicates
that there are currently no data available in this object.
When DTM_ASYNCLAYOUT is done, the layout deamon sends a notify msg
with the following tags:
{ GA_ID, Gadget ID },
{ DTA_Data, object },
{ DTA_TopVert, (dtsi -> si_TopVert) },
{ DTA_VisibleVert, (dtsi -> si_VisVert) },
{ DTA_TotalVert, (dtsi -> si_TotVert) },
{ DTA_TopHoriz, (dtsi -> si_TopHoriz) },
{ DTA_VisibleHoriz, (dtsi -> si_VisHoriz) },
{ DTA_TotalHoriz, (dtsi -> si_TotHoriz) },
{ DTA_Sync, TRUE },
{ DTA_Busy, FALSE }
SEE ALSO
datatypesclass/DTM_ASYNCLAYOUT
datatypes.library/DoDTDomainA datatypes.library/DoDTDomainA
NAME
DoDTDomainA -- Obtain the min/nom/max domains of a dt object (V45)
SYNOPSIS
retval = DoDTDomainA( o, win, req, rport, which, domain, attrs );
a0 a1 a2 a3 d0 a4 a5
ULONG DoDTDomainA( Object *, struct Window *, struct Requester *,
struct RastPort *, ULONG, struct IBox *, struct TagItem * );
retval = DoDTDomain( o, win, req, rport, which, domain, tag1,
... );
ULONG DoDTDomain( Object *, struct Window *, struct Requester *,
struct RastPort *, ULONG, struct IBox *, Tag, ... );
FUNCTION
INPUTS
o - Object like returned from NewDTObjectA
win - Window the object is attached to
req - Requester the object is attached to
rport - RastPort, used for domain calculations
which - one of the GDOMAIN_#? identifiers from
<intuition/gadgetclass.h>
domain - resulting domain box
attrs - Additional attributes
TAGS
Subclass specific.
Example:
DTA_TextAttr (struct TextAttr *) - Default object font
used for text calculations.
RETURNS
retval - The return value returned by GM_DOMAIN or 0UL for an error.
domain - On success, the domain box will be filled with the
gadget's domain dimensions for this particular GDOMAIN_#?
id.
EXAMPLE
See "Examples/dtrequester/dtrequester.c" or
"Examples/dtimage/dtimage.c".
NOTE
This function cannot handle the GM_DOMAIN method without
an object. To do this, you have to use CoreceMethodA
manually.
SEE ALSO
datatypesclass/GM_DOMAIN,
<intuition/gadgetclass.h>
datatypes.library/DoDTMethodA datatypes.library/DoDTMethodA
NAME
DoDTMethodA -- Do a datatypes method. (V39)
SYNOPSIS
retval = DoDTMethodA( o, win, req, msg );
d0 a0 a1 a2 a3
ULONG DoDTMethodA( Object *, struct Window *, struct Requester *,
Msg );
retval = DoDTMethod( o, win, req, data, ... );
ULONG DoDTMethod( Object *, struct Window *, struct Requester *,
ULONG, ... );
FUNCTION
This function is used to perform a method on a datatypes object.
INPUTS
o - Pointer to an object as returned by NewDTObjectA.
win - Pointer to a window that the object is attached to.
req - Pointer to a requester that the object is attached to. (V45)
msg - The message to send to the object.
RETURNS
retval - Returns the value returned by the method.
SEE ALSO
intuition.library/DoGadgetMethodA
datatypes.library/DrawDTObjectA datatypes.library/DrawDTObjectA
NAME
DrawDTObjectA -- Draw a DataTypes object. (V39)
SYNOPSIS
retval = DrawDTObjectA( rp, o, x, y, w, h, th, tv, attrs );
d0 a0 a1 d0 d1 d2 d3 d4 d5 a2
LONG DrawDTObjectA( struct RastPort *, Object *, LONG, LONG,
LONG, LONG, LONG, LONG,
struct TagItem * );
retval = DrawDTObject( rp, o, x, y, w, h, th, tv, tag1, ... );
LONG DrawDTObject( struct RastPort *, Object *, LONG, LONG,
LONG, LONG, LONG, LONG, Tag, ... );
FUNCTION
This function is used to draw a DataTypes object into a RastPort.
This function can be used for strip printing the object or
embedding it within a document.
You must successfully call ObtainDTDrawInfoA before using
this function.
This function invokes the object's DTM_DRAW method.
Clipping MUST be turned on within the RastPort. This means
that there must be a valid layer structure attached to the
RastPort, otherwise some datatypes can't draw (FALSE returned).
INPUTS
rp - Pointer to the RastPort to draw into.
Starting with V45, a NULL arg will result in a NOP.
o - Pointer to an object returned by NewDTObjectA.
Starting with V45, a NULL arg will result in a NOP.
x - Left edge of area to draw into.
y - Top edge of area to draw into.
w - Width of area to draw into.
h - Height of area to draw into.
th - Horizontal top in units.
tv - Vertical top in units.
attrs - Additional attributes.
TAGS
Good args args are ADTA_Frame for animationclass objects (requires
animationclass V41), which selects the frame beeing drawn.
RETURNS
TRUE to indicate that it was able to render, FALSE on failure;
EXAMPLES
See "Examples/dtimage/dtimage.c".
SEE ALSO
ObtainDTDrawInfo, ReleaseDTDrawInfo,
intuition.library/DrawImageState,
"Examples/dtimage/dtimage.c".
datatypes.library/FindMethod datatypes.library/FindMethod
NAME
FindMethod -- find a specified method in methods array (V45)
SYNOPSIS
method = FindMethod( methods, searchmethodid );
d0 a0 a1
ULONG *FindMethod( ULONG *, ULONG );
FUNCTION
This function searches for a given method in a given methods
array like got from GetDTMethods.
INPUTS
methods - methods array, like got from GetDTMethods or DTA_Methods
NULL is a valid arg.
searchmethodid - method id to find.
RETURNS
Pointer to the method table entry or NULL if not found.
EXAMPLE
/* This macro tests if a given method (like DTM_PRINT) is
* supported by the given object
*/
#define IsDTMethodSupported( o, id ) \
((BOOL)FindMethod(GetDTMethods( (o) ), (id) ))
SEE ALSO
GetDTMethods,
CopyDTMethods
datatypes.library/FindToolNodeA datatypes.library/FindToolNodeA
NAME
FindToolNodeA -- Find a tool node (V45)
SYNOPSIS
tn = FindToolNodeA( toollist, attrs );
d0 a0 a1
struct ToolNode *FindToolNodeA( struct List *,
struct TagItem * );
tn = FindToolNode( toollist, tag1, ... );
ULONG FindToolNode( struct List *, ... );
FUNCTION
This function searches for a given tool in a list of tool nodes.
INPUTS
toollist - struct List * or a struct ToolNode * (which will be
skipped) to search in.
NULL is a valid arg.
attrs - Search tags.
A NULL arg returns simple the following node.
TAGS
TOOLA_Program - name of the program to search for
TOOLA_Which - one of the TW_#? types.
TOOLA_LaunchType - Launch mode; TF_SHELL, TF_WORKBENCH or TF_RX
RETURNS
struct ToolNode * or NULL
EXAMPLE
See "Examples/DoDT/DoDT.c".
NOTE
This function is not limitted to the (&(DataType -> dtn_ToolList));
programmers can set up their own lists.
The (&(DataType -> dtn_ToolList)) entries are valid as long as
the application obtains a lock to the DataType (as obtained from
a dt object, ObtainDataTypeA or LockDataType).
SEE ALSO
LaunchToolA
datatypes.library/FindTriggerMethod datatypes.library/FindTriggerMethod
NAME
FindTriggerMethod -- find a specified trigger method in trigger
methods array (V45)
SYNOPSIS
method = FindTriggerMethod( dtm, command, method );
d0 a0 a1 d0
struct DTMethod *FindTriggerMethod( struct DTMethod *, STRPTR,
ULONG );
FUNCTION
This function searches for a given trigger method in a given methods
array like got from GetDTTriggerMethods.
If one of the "command" or "method" args matches a array item, this
function returns a pointer to it.
INPUTS
methods - trigger methods array, like got from GetDTTriggerMethods
or DTA_TriggerMethods.
NULL is a valid arg.
command - trigger method command name (case-insensitive match),
may be NULL (don't match).
method - trigger method id,
may be ~0UL (don't match).
RETURNS
Pointer to the trigger method table entry (struct DTMethod *) or
NULL if not found.
EXAMPLE
SEE ALSO
GetDTTriggerMethods,
CopyDTTriggerMethods
datatypes.library/FreeDTMethods datatypes.library/FreeDTMethods
NAME
FreeDTMethods -- Free methods array obtained by CopyDT#?Methods (V45)
SYNOPSIS
FreeDTMethods( methods );
a0
VOID FreeDTMethods( APTR );
FUNCTION
INPUTS
methods - Methods array, as obtained by CopyDTMethods or
CopyDTTriggerMethods. NULL is a valid input.
SEE ALSO
CopyDTMethods,
CopyDTTriggerMethods
datatypes.library/GetDTAttrsA datatypes.library/GetDTAttrsA
NAME
GetDTAttrsA -- Obtain attributes for an object. (V39)
SYNOPSIS
retval = GetDTAttrsA( o, attrs );
d0 a0 a2
ULONG GetDTAttrsA( Object *, struct TagItem * );
retval = GetDTAttrs( o, tag1, ... );
ULONG GetDTAttrs( Object *, Tag, ... );
FUNCTION
This function is used to get the attributes of a data type
object.
INPUTS
o - Pointer to an object as returned by NewDTObjectA.
A NULL arg is valid (V45).
attrs - Attributes to get, terminated with TAG_DONE. The data
element of each pair contains the address of the storage
variable.
A NULL arg is valid (V45).
TAGS
See datatypesclass/OM_GET and <datatypes/datatypesclass.h> for
attributes.
RETURNS
retval - Contains the number of attributes the system was able
to obtain.
SEE ALSO
datatypesclass/OM_GET,
SetDTAttrsA,
intuition.library/GetAttr
datatypes.library/GetDTMethods datatypes.library/GetDTMethods
NAME
GetDTMethods -- Obtain methods an object supports. (V39)
SYNOPSIS
methods = GetDTMethods( object );
d0 a0
ULONG *GetDTMethods( Object * );
FUNCTION
This function is used to obtain a list of methods that an
object supports.
INPUTS
object - Pointer to an object as returned by NewDTObjectA.
NULL is a valid arg (V45).
RETURNS
Returns a pointer to a ~0 terminated ULONG array. This array
is only valid until the object is disposed off.
NOTE
Some (interactive) objects may change the list of supported
methods during execution. This change is notified by
an OM_NOTIFY msg which contains the DTA_Sync tag.
SEE ALSO
GetDTTriggerMethods,
FindMethod,
datatypesclass/OM_GET
datatypes.library/GetDTString datatypes.library/GetDTString
NAME
GetDTString -- Obtain a DataTypes string. (V39)
SYNOPSIS
str = GetDTString( id );
d0 d0
STRPTR GetDTString( ULONG );
FUNCTION
This function is used to obtain a pointer to a localized
DataTypes string.
INPUTS
id - ID of the string to obtain.
RETURNS
A pointer to a NULL terminated string.
NOTE
- Error codes from 1-499 belongs to DOS, error codes from
500-999 belongs to ENVOY and error codes from 2000-2099
belongs to DataTypes. Codes between 2100 and 2999 are
used to access localizes DataTypes strings.
- Does not support the ENVOY error code nor the DOS error code space
(use dos.library/Fault in this case).
SEE ALSO
datatypes.library/GetDTTriggerMethodDataFlagsrary/GetDTTriggerMethodDataFlags
NAME
GetDTTriggerMethodDataFlags -- Get data type of dtt_Data value (V45)
SYNOPSIS
type = GetDTTriggerMethodDataFlags( method );
d0
ULONG GetDTTriggerMethodDataFlags( ULONG );
FUNCTION
This function returns the kind of data which can be attached
to the stt_Data field in the dtTrigger method body.
The data type can be specified by or'ing the method id (within
STMF_METHOD_MASK value) with one of the STMD_#? identifiers:
STMD_VOID - stt_Data MUST be NULL
STMD_ULONG - stt_Data contains an unsigned long value
STMD_STRPTR - stt_Data is a string pointer
STMD_TAGLIST - stt_Data points to an array of struct TagItem's,
terminated with TAG_DONE
The trigger methods below STM_USER are explicitly handeled, as
described in <datatypes/datatypesclass.h>, e.g. STM_COMMAND
return STMD_STRPTR, instead of STMD_VOID.
INPUTS
method - dtt_Method ID from struct DTMethod
RESULT
type - one of the STMD_#? identifies in <datatypes/datatypesclass.h>
EXAMPLE
struct DTMethod htmldtc_dtm[] =
{
/* ... */
"Stop Loading", "STOP", (STM_STOP | STMD_VOID),
"Load Images", "LOADIMAGES", ((STM_USER + 20) | STMD_VOID),
"Goto URL", "GOTOURL", ((STM_USER + 21) | STMD_STRPTR),
/* ... */
NULL, NULL, 0L
};
Sets up three methods:
"STOP" takes no arguments,
"LOADIMAGES" takes no arguments and
"GOTOURL" takes a STRPTR as an argument.
SEE ALSO
CopyDTTriggerMethods,
FindTriggerMethod,
datatypesclass/DTM_TRIGGER,
"Examples/dtrequester/dtrequester.c",
"Examples/CloneMethods/CloneMethods.c"
datatypes.library/GetDTTriggerMethods datatypes.library/GetDTTriggerMethods
NAME
GetDTTriggerMethods -- Obtain trigger methods supported by an object
(V39)
SYNOPSIS
methods = GetDTTriggerMethods( object );
d0 a0
struct DTMethod *GetDTTriggerMethods( Object * );
FUNCTION
This function is used to obtain a list of trigger methods that an
object supports. This is so that an application can provide
the appropriate controls (buttons etc.) for an object. For example,
an AmigaGuide object needs controls for "Contents", "Index",
"Retrace", "Browse <", and "Browse >",
INPUTS
object - Pointer to an object as returned by NewDTObjectA.
NULL is a valid arg (V45).
RETURNS
Returns a pointer to a STM_DONE terminated DTMethod list. This list
is only valid until the object is disposed off.
EXAMPLE
To call the method:
DoDTMethod( object, window, requester,
DTM_TRIGGER, NULL, (dtm[ button ] -> dtm_Method), NULL );
WARNING
Some trigger methods requires an argument. Calling them with
a NULL argument is WRONG. Use GetDTTriggerMethodDataFlags to
obtain the type of the requested argument (STMD_VOID means:
no arguments).
NOTE
Some (interactive) objects may change the list of supported
trigger methods during execution. This change is notified by
an OM_NOTIFY msg which contains the DTA_Sync tag.
SEE ALSO
GetDTMethods,
FindTriggerMethod,
datatypesclass/OM_GET
datatypes.library/LaunchToolA datatypes.library/LaunchToolA
NAME
LaunchToolA -- invoke a given tool with project (V45)
SYNOPSIS
success = LaunchToolA( tool, project, attrs );
d0 a0 a1 a2
ULONG LaunchToolA( struct Tool *, STRPTR, struct TagItem * );
success = LaunchTool( tool, project, tag1, ... );
ULONG LaunchTool( struct Tool *, STRPTR, ... );
FUNCTION
This function launches an application with a specified project.
The application and it's launch mode and other attributes are
specified through the "Tool" structure.
INPUTS
tool - Pointer to a Tool structure
NULL is a valid arg.
project - Name of the project to execute or NULL.
attrs - Additional attributes
TAGS
NP_Priority (BYTE) - sets the priority of the launched tool
Defaults to the current process's priority for
Shell and ARexx programs; Workbench applications
defaults to 0 except overridden by the TOOLPRI tooltype.
NP_Synchronous (BOOL) - don't return until lauched application proces
s
finishes.
Defaults to FALSE.
Other tags are __currently__ ignored.
RETURNS
FALSE for failure, non-zero for success.
EXAMPLE
See "Examples/DoDT/DoDT.c".
NOTE
- This function requrires the "RX" command when lauching ARexx
scripts.
- This function must be launched from a process, not a simple task.
- This function is not limitted to use the struct DataType -> dtn_Too
ls
tools. Applications can set up their own struct Tool's as long
as these structures contains no rubbish.
If you don't know the TW_#? ("which") type of your custom tool, set
tn_Which to TW_MISC.
TODO
- Should support multiple projects for WB programs.
- Shell tools should have a setable stack size...
BUGS
- The WB launcher does not search the WB path for "Default Tools".
- The "%a" (Arguments) option for shell launched tools does
currently not work.
Will be fixed.
- The path of the launched tools depends on the parents path.
If there is no path, shell tools can only launch other tools
with their full path.
SEE ALSO
FindToolNodeA
datatypes.library/LockDataType datatypes.library/LockDataType
NAME
LockDataType -- Lock a DataType structure. (V45)
SYNOPSIS
LockDataType( dtn );
a0
VOID LockDataType( struct DataType * );
FUNCTION
This function is used to lock a DataType structure obtained
by ObtainDataTypeA or a datatypes object (DTA_DataType attribute).
All calls to LockDataType or ObtainDataTypeA must match the same
number of ReleaseDataType calls, otherwise havoc will break out.
INPUTS
dtn - DataType structure returned by ObtainDataTypeA. NULL
is a valid input.
NOTE
This function has been made public to allow to get a DataType
structure from an object (DTA_DataType attribute), and remain the
reference valid after the object has been disposed off (which
unlocks the DataType structure locked in NewDTObjectA).
SEE ALSO
ObtainDataTypeA, ReleaseDataType
datatypes.library/NewDTObjectA datatypes.library/NewDTObjectA
NAME
NewDTObjectA -- Create an data type object. (V39)
SYNOPSIS
o = NewDTObjectA( name, attrs );
d0 d0 a0
Object *NewDTObjectA( APTR, struct TagItem * );
o = NewDTObject( name, tag1, ... );
Object *NewDTObject( APTR, Tag, ... );
FUNCTION
This is the method for creating datatype objects from
'boopsi' classes. (Boopsi' stands for "basic object-oriented
programming system for Intuition".)
You further specify initial "create-time" attributes for the
object via a TagItem list, and they are applied to the
resulting datatype object that is returned.
INPUTS
name - Name of the data source. Usually an existing file name.
attrs - Pointer to a taglist containing additional arguments.
TAGS
DTA_SourceType (ULONG) - Specify the type of source data;
such as coming from a file or clipboard. If source type is
clipboard, then the name field contains the numeric clipboard
unit.
Defaults to DTST_FILE.
DTA_Handle - Can optionally be used instead of the name field.
Must be a valid Lock (BPTR) if DTA_SourceType is DTST_FILE.
Must be a valid IFFHandle (struct IFFHandle *) if DTA_SourceType
is DTST_CLIPBOARD.
Must be NULL if DTA_SourceType is DTST_RAM.
DTA_DataType (struct DataType *) - Specify the class of data.
Data is a pointer to a valid DataType. This is only used when
attempting to create a new object that doesn't have any source
data or to force the library to use this class to handle the data
.
The datatype given will not be unlocked.
Defaults to NULL (use ObtainDataTypeA to determinate the file/
clipboard contents type).
DTA_BaseName (STRPTR) (V45) - Specify base name of datatype to use.
This tag should be used rarely (e.g. if a matching descriptor
does not exists). It must only be used with DTST_RAM.
Passing both DTA_BaseName and DTA_DataType causes havoc and must
be avoided.
DTA_Class (struct IClass *) (V45.3) - Specify the class to create an
object from. Usefull when creating private subclasses inside
applications (e.g. when a subclass is needed to superset some
methods (see "DTConvert" example)).
DTA_GroupID (ULONG) - Specify that the object must be of this type, o
r
NewDTObjectA will fail with IoErr of
ERROR_OBJECT_WRONG_TYPE.
Defaults to 0 (no specific group).
The following list is a collection of attributes recognized by some
subclasses. The "Defaults to" are only suggestions, and may or may
not have this value for a specific class:
DTA_TextAttr (struct TextAttr *) - Specify the default object font
which should be used.
Defaults to NULL.
DTA_NodeName (STRPTR) - Specify the node to load (for those
datatypes which splits their data into nodes, such as AmigaGuide
or SGML).
Defaults to "Main", which means the "Main" entry of the document.
DTA_Conductor (STRPTR) - specifies the name of the
realtime.library conductor (for syncronisation of events).
Defaults to (~0UL) (private conductor).
DTA_ControlPanel (BOOL) - Indicate whether a control panel should be
embedded within the object (like animation.datatype, for
example).
Defaults to TRUE.
DTA_Immediate (BOOL) - Indicate whether the object should immediate
begin playing.
Defaults to FALSE.
DTA_Repeat (BOOL) - Indicate whether the object should repeat playing
(the sound, sample, music or animation).
Defaults to FALSE.
DTA_ARexxPortName (STRPTR) - Base name for ARexx port
Defaults to
"<(struct DataTypesHeader -> dth_BaseName)>.<unique count>".
DTA_Progressive (BOOL) - Use progressive loading, if possible.
Defaults to FALSE.
GA_Left, GA_RelRight, GA_Top, GA_RelBottom, GA_Width, GA_RelWidth,
GA_Height, GA_RelHeight (WORD) - Specify the placement of the object
within the destination window.
GA_ID (UWORD) - Specify the object ID.
GA_UserData (ULONG) - Specify the application specific data for the
object.
DTA_UserData (ULONG) - Specify the application specific data for the
object.
RETURNS
A boopsi object, which may be used in different contexts such
as a gadget or image, and may be manipulated by generic functions.
You eventually free the object using DisposeDTObject.
A NULL return indicates failure. Use IoErr to get error value.
Following is a summary of the error number used and there meaning
as it relates to DataTypes.
ERROR_REQUIRED_ARG_MISSING - Indicates that a required attribute
wasn't passed in.
ERROR_BAD_NUMBER - An invalid group ID was passed in.
ERROR_OBJECT_WRONG_TYPE - Object data type doesn't match
DTA_GroupID.
ERROR_NO_FREE_STORE - Not enough memory.
DTERROR_UNKNOWN_DATATYPE - Unable to open the class library
associated with the data type.
DTERROR_COULDNT_OPEN - Unable to open the data object.
ERROR_NOT_IMPLEMENTED - Unknown handle type.
NOTES
This function invokes the OM_NEW "method" for the class specified.
EXAMPLE
STRPTR FileName = "S:User-Startup"
Object *o;
/* Simplest way is just to open an existing file */
if( o = NewDTObjectA( (APTR)FileName, NULL ) )
{
/* ... */
/* Get rid of the object when we are done with it */
DisposeDTObject( o );
}
BUGS
Before V45, creating a blank text object using
{ DTA_SourceType, DTSR_RAM },
{ DTA_GroupID, GID_TEXT },
tags, an "ascii.datatype" object was returned. Starting with
V45, NewDTObjectA returns now correctly a "text.datatype" object.
SEE ALSO
AddDTObject, DisposeDTObject, RemoveDTObject,
intuition.library/NewObjectA,
datatypesclass/OM_NEW
datatypes.library/ObtainDataTypeA datatypes.library/ObtainDataTypeA
NAME
ObtainDataTypeA -- Examines a handle and return its DataType. (V39)
SYNOPSIS
dtn = ObtainDataTypeA( type, handle, attrs );
d0 d0 a0 a1
struct DataType *ObtainDataTypeA( ULONG, APTR, struct TagItem * );
dtn = ObtainDataType( type, handle, tag1, ... );
struct DataType *ObtainDataType( ULONG, APTR, Tag, ... );
FUNCTION
This function examines the data that the handle points to,
and returns a DataType record that describes the data.
INPUTS
type - Type of handle (one of the DTST_#? handle types).
handle - Handle to examine.
For DTST_FILE, handle must be BPTR lock.
For DTST_CLIPBOARD, handle must be struct IFFHandle *.
For DTST_RAM (V45), handle must be a STRPTR (DataType
name, equals to the dtn_Name field).
For DTST_HOTLINK NOT IMPLEMENTED YET
The handle given will not be unlocked/freed.
attrs - Additional attributes.
DTA_GroupID (ULONG) (V45) - GID_#? group to match
0 is a valid input.
DTA_DataType (struct DataType *) (V45) - Search in descriptor
list starts at this point (maybe result
of a previous datatype).
The given datatype will NOT be unlocked.
NULL is a valid input (start at the begin
of list).
NOTES
- The datatypes.library maintains a sorted list of all the DataType
descriptors. The descriptor can consist of a function, a data mask
for the first 64 bytes of the data, and a name pattern.
The sort order for the list is:
Descriptors with a function and no mask or name pattern.
Descriptors with a function and a mask or name pattern.
Descriptors with no function and a mask or name pattern.
Within each group, they are also sorted in descending priority
and descending mask length.
- ObtainDataTypeA calls with same parameters may return a different
struct DataType *.
Same datatypes have the same dth_Name
RETURNS
Success returns a pointer to a DataType. You must call
ReleaseDataType when you are done with the handle.
A NULL return indicates failure. Use IoErr to get error value.
Following is a summary of the error number used and there meaning
as it relates to DataTypes.
ERROR_NO_FREE_STORE - Not enough memory.
DTERROR_COULDNT_OPEN - Unable to open the data object.
ERROR_NOT_IMPLEMENTED - Unknown handle type.
ERROR_INVALID_LOCK - DTA_DataType attribute passed in
wasn't valid (V45).
BUGS
Before V45, passing a user-defined struct DataType (e.g. the
dtn_Length is 0UL) to datatypes.library functions may causes
crashes.
EXAMPLE
See "Examples/dtdescrlist/dtdescrlist.c"
SEE ALSO
ReleaseDataType, LockDataType,
"Examples/dtdescrlist/dtdescrlist.c"
datatypes.library/ObtainDTDrawInfoA datatypes.library/ObtainDTDrawInfoA
NAME
ObtainDTDrawInfoA -- Obtain a DataTypes object for drawing. (V39)
SYNOPSIS
handle = ObtainDTDrawInfoA( o, attrs );
d0 a0 a1
APTR ObtainDTDrawInfoA( Object *, struct TagItem * );
handle = ObtainDTDrawInfo( o, tag1, ... );
APTR ObtainDTDrawInfo( Object *, Tag, ... );
FUNCTION
This function is used to prepare a DataTypes object for
drawing into a RastPort.
This function will send the DTM_OBTAINDRAWINFO method
to the object using the opSet message structure.
INPUTS
o - Pointer to an object as returned by NewDTObjectA.
Starting with V45, a NULL arg results in a NOP.
attrs - Additional attributes.
RETURNS
Returns a PRIVATE handle that must be passed to ReleaseDTDrawInfo
when the application is done drawing the object.
A NULL return value indicates failure.
TAGS
Good args are
PDTA_Screen for pictureclass objects and
ADTA_Screen for animationclass objects.
EXAMPLE
See "Examples/dtimage/dtimage.c".
NOTE
You cannot handle the same datatypesclass object as a gadget in
a window/requester and as a image using ObtainDTDrawInfoA/
DrawDTObjectA/ReleaseDTDrawInfo at the same time.
But using it as a gadget, then remove it from window, then use it as
an image is valid and __must__ be supported.
SEE ALSO
DrawDTObjectA, ReleaseDTDrawInfo,
"Examples/dtimage/dtimage.c"
datatypes.library/PrintDTObjectA datatypes.library/PrintDTObjectA
NAME
PrintDTObjectA -- Call the DTM_PRINT method on a separate process.
(V39)
SYNOPSIS
retval = PrintDTObjectA( object, window, requester, msg );
d0 a0 a1 a2 a3
ULONG PrintDTObjectA( Object *, struct Window *, struct Requester *,
struct dtPrint * );
retval = PrintDTObject( object, window, requester, data, ... );
ULONG PrintDTObject( Object *, struct Window *, struct Requester *,
ULONG, ... );
FUNCTION
This function is used to asyncronously perform the object's DTM_PRINT
method.
Once the application has performed the PrintDTObjectA function,
it must not manipulate the printerIO union until it receives a
OM_UPDATE message that contains the DTA_PrinterStatus tag.
To abort a print, the application sends the DTM_ABORTPRINT method
to the object. This in turn signals the print process with a
SIGBREAKF_CTRL_C.
Starting with V45, the stack size of the print daemon process
increases from 4096 up to 8192 bytes.
INPUTS
object - Pointer to the DataTypes object.
window - Pointer to the window that the object has been added to.
requester - Pointer to the requester that the object has been
added to (V45).
msg - Pointer to struct dtPrint message
RETURNS
Returns TRUE if successful, FALSE on error (anoter print in process).
NOTE
When the DTM_PRINT method is done, the print daemon triggers a notify
msg with following contents:
{ GA_ID, GadgetID },
{ DTA_PrinterStatus, dtm_print_retval }
SEE ALSO
datatypesclass/DTM_PRINT,
datatypesclass/DTM_ABORTPRINT
datatypes.library/RefreshDTObjectA datatypes.library/RefreshDTObjectA
NAME
RefreshDTObjectA -- Refresh a datatypes object. (V39)
SYNOPSIS
RefreshDTObjectA( object, window, req, attrs )
a0 a1 a2 a3
VOID RefreshDTObjectA( Object *, struct Window *,
struct Requester *, struct TagItem * );
RefreshDTObject( object, window, req, tag1, ... );
VOID RefreshDTObject( Object *, struct Window *,
struct Requester *, Tag, ... );
FUNCTION
Refreshes the specified object, by sending the GM_RENDER method to
the object.
INPUTS
object - Pointer to an object as returned by NewDTObjectA.
NULL is a valid arg (V45).
window - Pointer to the window.
NULL is a valid arg (V45).
req - Pointer to the requester (V45).
attrs - Additional attributes (currently none are defined).
SEE ALSO
AddDTObject, RemoveDTObject,
intuition.library/RefreshGList
datatypes.library/ReleaseDataType datatypes.library/ReleaseDataType
NAME
ReleaseDataType -- Release a DataType structure. (V39)
SYNOPSIS
ReleaseDataType( dtn );
a0
VOID ReleaseDataType( struct DataType * );
FUNCTION
This function is used to release a DataType structure obtained
by ObtainDataTypeA.
INPUTS
dtn - DataType structure returned by ObtainDataTypeA. NULL
is a valid input.
BUGS
Before V45, passing a user-defined struct DataType (e.g. the
dtn_Length is 0UL) may causes crashes.
NOTE
Starting with V45.4, ReleaseDataType throws an Alert (AN_Unknown)
if a mismatched (e.g. too many ReleaseDataType's) ReleaseDataType
was triggered.
SEE ALSO
ObtainDataTypeA, LockDataType
datatypes.library/ReleaseDTDrawInfo datatypes.library/ReleaseDTDrawInfo
NAME
ReleaseDTDrawInfo -- Release a DataTypes object from drawing. (V39)
SYNOPSIS
ReleaseDTDrawInfo( o, handle );
a0 a1
VOID ReleaseDTDrawInfo( Object *, APTR );
FUNCTION
This function is used to release the information obtained
with ObtainDTDrawInfoA.
This function invokes the object's DTM_RELEASEDRAWINFO method
using the dtReleaseDrawInfo message structure.
INPUTS
o - Object returned by NewDTObjectA.
Starting with V45, a NULL arg results in a NOP.
handle - Pointer to an private handle obtained by ObtainDTDrawInfoA.
EXAMPLE
See "Examples/dtimage/dtimage.c".
SEE ALSO
DrawDTObjectA, ObtainDTDrawInfoA,
"Examples/dtimage/dtimage.c".
datatypes.library/RemoveDTObject datatypes.library/RemoveDTObject
NAME
RemoveDTObject -- Remove an object from a window. (V39)
SYNOPSIS
position = RemoveDTObject( window, object );
d0 a0 a1
LONG RemoveDTObject( struct Window *, Object * );
FUNCTION
Removes the object from the window's object list. This will wait
until the AsyncLayout process is complete. The object will
receive a DTM_REMOVEDTOBJECT message to inform the object will
be removed.
If the gadget was in a requester, the GTYP_REQGADGET flag will
be cleared.
INPUTS
window - Pointer to the window.
object - Pointer to an object as returned by NewDTObjectA.
NULL is a valid arg (V45).
RETURNS
Returns the ordinal position of the removed object. If the
object wasn't found in the appropriate list then a -1 is
returned.
NOTE
Note that this function __MUST__ not be uses when a datatype
object is embedded within another BOOPSI gadget. The
parent object is responsible to pass all required methods
including initial GM_LAYOUT and DTM_REMOVEDTOBJECT to
the embedded object.
SEE ALSO
AddDTObject,
intuition.library/RemoveGList,
datatypesclass/DTM_REMOVEDTOBJECT
datatypes.library/rexx/--rexxhost-- datatypes.library/rexx/--rexxhost--
HOST INTERFACE
datatypes.library provides an ARexx function host interface that
enables ARexx programs to take advantage of the features of data
types. The functions provided by the interface are directly
related to the functions described herein, with the differences
mostly being in the way they are called.
The function host library vector is located at offset -30 from
the library. This is the value you provide to ARexx in the
ARexx AddLib function call.
FUNCTIONS
EXAMINEDT - Examine file
OBTAINDATATYPE - Obtain datatype from a given file, clipboard or
by other specs
FINDTTOOL - Find a tool by name, type etc.
LAUNCHTOOL - Launch a tool
OBTAINDTSTRING - Obtain datatypes string
(DEBUG - __PRIVATE__ (Debugging control))
datatypes.library/rexx/EXAMINEDT datatypes.library/rexx/EXAMINEDT
NAME
EXAMINEDT -- Examine given file
SYNOPSIS
EXAMINEDT( FILENAME/A, STEM, STORAGE )
FUNCTION
EXAMINEDT obtains data type and other attributes of the given
filesystem object.
INPUTS
FILENAME - filesystem object (file/dir/etc.) to examine
STEM - Name of stem variable to store data in
STORAGE - Type of result storage, one of "STEM" or "VAR"
RESULTS
If STORAGE was set to "VAR", the result is the datatype name.
On error, the numeric DOS error code is returned.
If STORAGE was set to "STEM" (and a stem var was given), the
stem var has the following members:
DISKKEY Filesystem disk key
DIRENTRYTYPE Dir Entry Type, one of
1 root directory (for UNIX fs)
2 directory
3 soft link (looks like dir, but may point to a
file !)
4 hard link to directory
-3 file
-4 hard link to file
-5 pipe file
FILENAME File Name
PROTECTION Protection
OTHERPROTECTION Other Protection
GROUPPROTECTION Group Protection
ENTRYTYPE Entry Type, see DIRENTRYTYPE for types
SIZE Size of file in bytes
NUMBLOCKS Blocks
DATE Date (AmigaDOS style)
COMMENT Comment
OWNERUID Owner User ID
OWNERGID Owner Group ID
OWNERUIDNAME Owner User Name
OWNERGIDNAME Owner Group Name
BASETYPE Type, one of "binary", "ascii", "iff" or "other"
BASETYPENAME Localiued form of BASETYPE
DATATYPE File Type
BASENAME Base Name
GROUPID DataTypes GroupID, like "syst", "text", "docu",
...
GROUPIDNAME Localized format of GROUPID, like "System", "Text",
"Document", ...
The function result contains the error code, (0 on success,
1 - 2099 otherwise).
EXAMPLE
/* examinedt.rexx */
PARSE ARG fname
OPTIONS RESULTS
/* Load the datatypes.library as a function host */
IF ~SHOW( 'L', 'datatypes.library' ) THEN
CALL ADDLIB( 'datatypes.library', 0, -30 )
IF fname="" THEN DO
SAY "Usage:"
SAY " rx examinedt <filename>"
EXIT
END
SAY 'var test'
type = ExamineDT( fname,,VAR )
SAY type
SAY 'stem test'
CALL ExamineDT( fname, dtstem., STEM )
SAY ' Disk Key:' dtstem.DiskKey
SAY ' Dir Entry Type:' dtstem.DirEntryType
SAY ' File Name:' dtstem.FileName
SAY ' Protection:' dtstem.Protection
SAY ' Other Protection:' dtstem.OtherProtection
SAY ' Group Protection:' dtstem.GroupProtection
SAY ' Entry Type:' dtstem.EntryType
SAY ' Size:' dtstem.Size
SAY ' Blocks:' dtstem.NumBlocks
SAY ' Date:' dtstem.Date
SAY ' Comment:' dtstem.Comment
SAY ' Owner User ID:' dtstem.OwnerUID
SAY ' Owner Group ID:' dtstem.OwnerGID
SAY ' Owner User Name:' dtstem.OwnerUIDName
SAY ' Owner Group Name:' dtstem.OwnerGIDName
SAY ' Type:' dtstem.BaseType
SAY ' File Type:' dtstem.DataType
SAY ' Base Name:' dtstem.BaseName
SAY ' DT GroupID:' dtstem.GroupID
EXIT
NOTE
- Owner User Name and Owner Group Name requires fs support for
ACTION_UID2UNAME and ACTION_GID2GNAME (like envoy fs).
- Error handling has been changed in V45. On error, the function
now returns the error number (1 - 2099), which can be converted
using rexx/GETDTSTRING; only serious errors (like "non memory")
will end in a rexx error code.
SEE ALSO
rexx/OBTAINDATATYPE
datatypes.library/rexx/FINDTOOL datatypes.library/rexx/FINDTOOL
NAME
FINDTOOL -- Find a single tool stem from given pattern
SYNOPSIS
FINDTOOL( TOOLLISTSTEM/A, START/N, PROGRAM, WHICH, LAUNCHTYPE )
FUNCTION
Find a single tool stem within a TOOLLIST stem as returned by
OBTAINDATATYPE
INPUTS
TOOLLISTSTEM -- a stem variable with TOOL stems and a TOOLLIST.COUNT
var.
START - Start index, beginning from 0.
Note that the goven index will be skipped, and the search
starts at the following node.
Defaults to -1 (e.g. next node is 0).
WHICH - Type of application
One of "misc", "info", "browse", "edit", "print",
"mail".
Defaults to "", which means: Match all Which-Types
LAUNCH - Launch mode, one of "shell", "workbench", "rx"
Defaults to "", which means: Match all Launch-modes
PROGRAM - Full path of the program to be launched
RETURNS
The index of the toolstem found or -1.
EXAMPLE
NOTE
SEE ALSO
rexx/OBTAINDATATYPE
datatypes.library/rexx/GETDTSTRING datatypes.library/rexx/GETDTSTRING
NAME
GETDTSTRING -- Get (localized) datatypes string
SYNOPSIS
GETDTSTRING( ID/A, NAME )
FUNCTION
Gets a (localized) datatypes string and returns it in RESULT.
INPUTS
ID -- string number, like DTERROR_#? from
include:datatypes/datatypes.h
2000 - "Unknown data type for %s"
and so on...
or
one of "syst#?", "docu#?", ...
or
one of "binary", "ascii", "iff", "other" (or "Miscellaneous")
Error codes from 1-499 belongs to DOS, error codes from
500-999 belongs to ENVOY and error codes from 2000-2099
belongs to DataTypes. Codes between 2100 and 2999 are
used to access localizes DataTypes strings.
NAME -- Name be be inserted into the string
RETURNS
string
EXAMPLE
NOTE
- Does not support the envoy error code space.
SEE ALSO
datatypes.library/rexx/LAUNCHTOOL datatypes.library/rexx/LAUNCHTOOL
NAME
LAUNCHTOOL -- Lauch a tool from given spec
SYNOPSIS
LAUNCHTOOL( TOOLSTEM/A, PROJECT, SYNCHRONOUS=SYNC/S, PRIORITY/N )
FUNCTION
Lauch a tool with an argument (e.g. project file). As set by the
TOOL stem, the tool may be lauched from Shell, from Workbench or
from ARexx.
INPUTS
TOOLSTEM -- a stem variable with following members
(this stem var is normally set up by OBTAINDATATYPE (TOOLLIST
stem)):
WHICH - Type of application
One of "misc", "info", "browse", "edit", "print",
"mail".
If you don't know the "which"-type of your tool,
set this to "misc".
LAUNCH - Launch mode, one of "shell", "workbench", "rx"
PROGRAM - Full path of the program to be launched
PROJECT -- Name of the project file to be used (passed as
an argument to the appliaction).
SYNCHRONOUS
SYNC -- Wait for child exit ?
If set, LaunchTool waits until the invoked program quits.
PRIORITY -- Set task priority of the lauched application.
RETURNS
Success or failure
EXAMPLE
NOTE
SEE ALSO
rexx/OBTAINDATATYPE
datatypes.library/rexx/OBTAINDATATYPE datatypes.library/rexx/OBTAINDATATYPE
NAME
OBTAINDATATYPE -- Obtain datatype from given #?
SYNOPSIS
OBTAINDATATYPE( TYPE/A, HANDLE/A, STEM/A, DATATYPE, GID )
FUNCTION
INPUTS
TYPE -- Type of HANDLE data
One of "RAM", "CLIPBOARD", "FILE" or "HOTLINK"
HANDLE -- Handle type.
For TYPE = "RAM", this is the DataType name to be searched
for. An empty string is treated as an NULL arg.
For TYPE = "CLIPBOARD", this is the numeric clipboard unit.
For TYPE = "FILE", this is the full path of a file/dir
to be examined.
TYPE = "HOTLINK" is not implemented yet.
STEM -- Name of the result stem var
DATATYPE -- Name of the datatype to start at. Used when scanning
the descriptor list.
GID -- Group ID filter, one of "System", "Text", "Document", "Sound",
"Instrument", "Music", "Picture", "Animation", "Movie".
If set, only descriptors of this type will be returned.
RETURNS
Success or failure
The given stem var has the following members:
HEADER.NAME - Name of the descriptor
HEADER.BASENAME - Base name (class library name)
HEADER.PATTERN - File pattern
HEADER.GROUPID - Group ID, one of "syst", "text", "docu", "soun",
"inst", "musi", "pict", "anim", "movi"
HEADER.GROUPIDNAME - Localized format of HEADER.GROUPID, (e.g.
"System", "Text", ...
HEADER.ID - For IFF datatypes, this is the IFF FORM code,
for other datatypes these are the first four
letters of the name field
HEADER.BASETYPE - Base type, on of "binary", "ascii", "iff", "other"
HEADER.BASETYPENAME - Localized format of HEADER.BASETYPE (e.g.
"Binary", "ASCII", "IFF", "Miscellaneous"
FUNCTIONNAME - Name of comparisation function
ATTRLIST - Stem list of datatype prefs tag items
ATTRLIST.COUNT - Total number of attributes
ATTRLIST.i.TAG - Name of tag
ATTRLIST.i.DATA - Data value
(Not functional without "objecttools.library".)
TOOLLIST. - Tool nodes stem list, with following members
TOOLLIST.COUNT - Total number of tool nodes in this list
TOOLLIST.i.WHICH - "Which" sort of program, one of "misc",
"info", "browse", "edit", "print", "mail", "undefined"
TOOLLIST.i.LAUNCH - Launch mode of tool, one of "shell",
"workbench", "rx", "undefined"
TOOLLIST.i.PROGRAM - Full path of the tool
TOOLLIST.i.FLAGS - Hex-Version of toolnodes "flags" field,
usage should be rare...
'i' above means loop-"interator".
EXAMPLE
/* $VER: obtaindatatype.rexx 1.1 (19.5.97) */
PARSE ARG fname
OPTIONS RESULTS
/* Load the datatypes.library as a function host */
IF ~SHOW( 'L', 'datatypes.library' ) THEN
CALL ADDLIB( 'datatypes.library', 0, -30 )
IF fname="" THEN DO
SAY "Usage:"
SAY " rx obtaindatatype <filename>"
EXIT
END
SAY 'stem test'
CALL ObtainDataType( FILE, fname, dtstem. )
SAY ' Name:' dtstem.header.name
SAY ' Basename:' dtstem.header.basename
SAY ' Pattern:' dtstem.header.pattern
SAY ' GroupID:' dtstem.header.groupid
SAY ' ID:' dtstem.header.id
SAY ' Basetype:' dtstem.header.basetype
SAY ' Functionname:' dtstem.functionname
/* ATTRLIST not set up in V45 */
DO i = 0 TO (dtstem.toollist.count - 1)
SAY 'Tool Node ' i
SAY ' Program:' dtstem.toollist.i.program
SAY ' Which:' dtstem.toollist.i.which
SAY ' Launch:' dtstem.toollist.i.launch
SAY ' Flags:' dtstem.toollist.i.flags
END
EXIT
NOTE
Without objecttools.library, struct DataType -> dtn_AttrList cannot
be converted into STEM vars.
SEE ALSO
rexx/EXAMINEDT,
rexx/LAUNCHTOOL
datatypes.library/SaveDTObjectA datatypes.library/SaveDTObjectA
NAME
SaveDTObjectA -- Save object's contents (V45)
SYNOPSIS
success = SaveDTObjectA( o, win, req, file, mode, saveicon, attrs );
d0 a0 a1 a2 a3 d0 d1 a4
SaveDTObjectA( Object *, struct Window *, struct Requester *,
STRPTR, ULONG, BOOL, struct TagItem * );
success = SaveDTObject( o, win, req, file, mode, saveicon, tag1,
... );
SaveDTObject( Object *, struct Window *, struct Requester *,
STRPTR, ULONG, BOOL, Tag, ... );
FUNCTION
This function saves the contents of an object into a file.
The function opens the named file and saves the object's contexts
into it (DTM_WRITE). Then it closes the file.
If the DTM_WRITE method returns success and the saveicon option is
TRUE, matching icon is saved.
If DTM_WRITE returns 0, the file will be deleted.
INPUTS
o - Object like returned from NewDTObjectA
win - Window the object is attached to
req - Requester the object is attached to
file - file name to save to
mode - Save mode, (RAW, IFF etc.), one of the DTWM_#? identifiers
saveicon - Save icon ?
attrs - Additional attributs
TAGS
Subclass specific.
For example, animation.datatype V41 recognizes ADTA_Frame (start
frame to save) and ADTA_Frames (number of frames to save).
RETURNS
success - The return value returned by DTM_WRITE or NULL for an
error.
BUGS
- Does currently not delete the file on failure.
- In V45.2 and before, the file was closed after the icon was
written. This caused Workbench to show the size of the icon
instead of the real file.
Fixed.
- Starting with V45.3, the return value of Close will be watched
correctly and may cause failure of this function.
SEE ALSO
datatypesclass/DTM_WRITE
datatypes.library/SetDTAttrsA datatypes.library/SetDTAttrsA
NAME
SetDTAttrsA -- Set attributes for an object. (V39)
SYNOPSIS
retval = SetDTAttrsA( o, win, req, attrs );
d0 a0 a1 a2 a3
ULONG SetDTAttrsA( Object *, struct Window *, struct Requester *,
struct TagItem * );
retval = SetDTAttrs( o, win, req, tag1, ... );
ULONG SetDTAttrs( Object *, struct Window *, struct Requester *,
Tag, ... );
FUNCTION
This function is used to set the attributes of a data type
object.
INPUTS
o - Pointer to an object as returned by NewDTObjectA.
win - Window that the object has been added to.
req - Requester that the object has been added to (V45).
attrs - Attributes to set.
TAGS
See datatypesclass/OM_SET and <datatypes/datatypesclass.h> for tags.
SEE ALSO
datatypesclass/OM_SET,
GetDTAttrsA,
intuition.library/SetGadgetAttrsA
datatypes.library/StartDragSelect datatypes.library/StartDragSelect
NAME
StartDragSelect -- Start drag-selection (V45)
SYNOPSIS
success = StartDragSelect( o );
d0 a0
ULONG StartDragSelect( Object * );
FUNCTION
This function starts drag-selection by the user (marking).
This function replaces the old flag-fiddling method to
start drag-select.
The drag-select will only be started of the object supports
DTM_SELECT, is in a window or requester and no layout-process
is working on the object. If all conditions are good, it sets
the DTSIF_DRAGSELECT flag and returns TRUE for success.
Starting with V45.4 Resul2 (IoErr()) contains some extra info
about the cause:
ERROR_ACTION_NOT_KNWON -- DTM_SELECT not supported
ERROR_OBJECT_IN_USE -- async layout etc. peding etc.
INPUTS
o - object like returned from NewDTObjectA
RETURNS
TRUE for success, FALSE for failure
SEE ALSO
datatypesclass/--datasheed-- datatypesclass/--datasheed--
NAME
datatypesclass -- base class for DataTypes
SUPERCLASS
gadgetclass
FUNCTION
This class is the "base" class for all datatypes. It provides basic
services and attributes.
METHODS
DTM_ABORTPRINT -- Abort an asyncronous print process
DTM_ASYNCLAYOUT -- Layout occuring on a seperate process
DTM_FRAMEBOX -- Query or set the environment an object will enter
DTM_PRINT - Print objects contents
DTM_PROCLAYOUT -- Layout object on application process
DTM_REMOVEDTOBJECT -- Remove object from window
DTM_WRITE -- Write objects contents to file
GM_DOMAIN -- Obtain the min./nom./max. dimensions of an object
GM_GOACTIVE -- Activate object
GM_GOINACTIVE -- Deactivate object
GM_HANDLEINPUT -- Handlde user input
GM_HITTEST -- Check if object was hit
GM_LAYOUT -- Layout object
OM_DISPOSE -- Dispose object
OM_GET -- Obtain the value of an attribute
OM_NEW -- Create an dt object
OM_SET -- Set the values of various attributes
OM_UPDATE -- Update the values of various attributes
ATTRIBUTES
The following attributes are used by datatypes. Note that
there is a difference between "Application"- and "Subclass"-
applicability. The following list are assumptions "How the
interface should work".
/* Generic attributes */
DTA_TextAttr (struct TextAttr *) - Pointer to the default TextAttr
to use for the text within the object.
Applicability for applications is (IG),
Applicability for subclasses is (SG).
DTA_TopVert (LONG) - Current top vertical unit
Applicability for applications is (ISG),
Applicability for subclasses is (SGNU).
DTA_VisibleVert (LONG) - Number of visible vertical units
Applicability for applications is (ISG),
Applicability for subclasses is (SGNU).
DTA_TotalVert (LONG) - Total number of vertical units
Applicability for applications is (ISG),
Applicability for subclasses is (SGNU).
DTA_VertUnit (LONG) - Number of pixels per vertical unit
Applicability for applications is (ISG),
Applicability for subclasses is (SGNU).
DTA_TopHoriz (LONG) - Current top horizontal unit
Applicability for applications is (ISG),
Applicability for subclasses is (SGNU).
DTA_VisibleHoriz (LONG) - Number of visible horizontal units
Applicability for applications is (ISG),
Applicability for subclasses is (SGNU).
DTA_TotalHoriz (LONG) - Total number of horizontal units
Applicability for applications is (ISG),
Applicability for subclasses is (SGNU).
DTA_HorizUnit (LONG) - Number of pixels per horizontal unit
Applicability for applications is (ISG),
Applicability for subclasses is (SGNU).
DTA_NodeName (STRPTR) - Name of the current element within the
object.
Applicability for applications is (ISG),
Applicability for subclasses is (SG).
DTA_Title (STRPTR) - Title of the object.
Applicability for applications is (),
Applicability for subclasses is (N).
DTA_TriggerMethods (struct DTMethod *) - Pointer to a STM_END-
terminated array of supported trigger methods.
(Subclasses may superset to extend this array using
CopyDTTriggerMethods).
Applicability for applications is (G),
Applicability for subclasses is (G).
DTA_Data (Object *) - Object itself.
Starting with V45, a DTA_Data == NULL indicates that
an object hasn't loaded all data yet (progressive loading,
see DTA_Progressive).
(Subclasses which implements progressive loading are forced
to superset OM_GET to indicate with a DTA_Data == NULL
that loading is currently in process).
Applicability for applications is (G),
Applicability for subclasses is (G).
DTA_TextFont (struct TextFont *) - Default font to use for text
within the object.
(This attribute is for subclasses only. Their superclass
(like text.datatype) will open this font and release it on
disposal).
Applicability for applications is (),
Applicability for subclasses is (G).
DTA_Methods (ULONG *) - Pointer to a ~0UL terminated array of
supported methods. (Subclasses may superset OM_GET to replace
the array with it's extendet array (created using CopyDTMethods))
Applicability for applications is (G),
Applicability for subclasses is (G).
DTA_PrinterStatus (LONG) - Printer error message. Error numbers are
defined in <devices/printer.h>, PDERR_#? identifiers.
This tag is notified from the AsyncPrintDaemon, based on the
return value of DTM_PRINT.
Applicability for applications is (),
Applicability for subclasses is ().
DTA_PrinterProc (struct Process *) - PRIVATE !!
Pointer to the print process.
DTA_LayoutProc (struct Process *) - PRIVATE !!
Pointer to the layout process.
DTA_Busy (BOOL) - Used to turn the applications' busy pointer off
and on.
Applicability for applications is (),
Applicability for subclasses is (N).
DTA_Sync (BOOL) - Used to indicate that new information has been
loaded into an object. A value of 0 indicates that the object is
still loading (DTA_Progressive == TRUE).
Applicability for applications is (),
Applicability for subclasses is (N).
DTA_BaseName (STRPTR) - The base name of the class (library).
This tag is currently only used by datatypes.library functions,
not by the class itself.
DTA_GroupID (ULONG) - The group a datatype must belong in (one of the
GID_#? identifiers in <datatypes/datatypes.h>).
This tag is currently only used by datatypes.library functions,
not by the class itself.
DTA_ErrorLevel (LONG) - Error level (one of the RETURN_#? levels
defined in <dos/dos.h>.
Applicability for applications is (),
Applicability for subclasses is (N).
DTA_ErrorNumber (LONG) - dos.library/datatypes.library error number,
one of the ERROR_#? identifiers defined in <dos/dos.h> or
one of the DTERROR_#? identifiers defined in
<datatypes/datatypes.h>
Applicability for applications is (),
Applicability for subclasses is (N).
DTA_ErrorString (STRPTR) - Argument for datatypes.library error
(e.g. if the error string has a %s included...).
Applicability for applications is (),
Applicability for subclasses is (N).
DTA_Conductor (STRPTR) - Specifies the name of the realtime.library
conductor. Will be passed to realtime.library/CreatePlayerA,
a value of ~0UL sets up a private conductor (recommned).
Applicability for applications is (I),
Applicability for subclasses is ().
DTA_ControlPanel (BOOL) - Indicate whether a control panel should be
embedded within the object (in the animation datatype, for
example).
Applicability for applications is (IS),
Applicability for subclasses is ().
DTA_Immediate (BOOL) - Indicate whether the object should immediately
begin playing.
Applicability for applications is (IS),
Applicability for subclasses is ().
DTA_Repeat (BOOL) - Indicate that the object should repeat playing.
Applicability for applications is (IS),
Applicability for subclasses is ().
DTA_Progressive (BOOL) - Indicate that the object should use
progressive loading. The datatype will send { DTA_Sync, 0UL }
notify msgs while loading is in progress; a final
{ DTA_Sync, 1UL } indicates that loading has been finished.
Applications have to OM_GET DTA_Data to check if loading
has __REALLY__ been finished. If "Object" is returned
loading is done, a NULL return value indicates that the object
is still loading.
Applicability for applications is (IS),
Applicability for subclasses is ().
DTA_CurrentLevel (ULONG) - Notifies the filling level of the object
when doing (progressive) loading. 0UL means 0%,
0xFFFFFFFFUL means 100%.
Applicability for applications is (),
Applicability for subclasses is (N).
DTA_ARexxPortName (STRPTR) - Pointer to base name for ARexx port
Applicability for applications is (I),
Applicability for subclasses is ().
/* DTObject attributes */
DTA_Name (STRPTR) - (File-)Name of object
Applicability for applications is (IG),
Applicability for subclasses is (G).
DTA_SourceType (ULONG) - One of the DTST_#? identifiers
Applicability for applications is (IG),
Applicability for subclasses is (G).
DTA_Handle (APTR) - Source handle. See OM_GET for the specific
handle type (BPTR fh, struct IFFHandle *, BPTR lock).
Note that the handle passed at OM_NEW will NOT be the same handle
you'll get with OM_GET.
Applicability for applications is (IG),
Applicability for subclasses is (G).
DTA_DataType (struct DataType *) -- datatype for this class.
Applicability for applications is (G),
Applicability for subclasses is (G).
DTA_Domain (struct IBox *) -- Domain box of gadget in absolute
dimensions.
Applicability for applications is (G),
Applicability for subclasses is (G).
DTA_ObjName,
DTA_ObjAuthor,
DTA_ObjAnnotation,
DTA_ObjCopyright and
DTA_ObjVersion all (STRPTR) -- The name, author etc. of the source
data.
Applicability for applications is (G),
Applicability for subclasses is (SG).
DTA_ObjectID (ULONG) -- RESERVED
DTA_UserData (ULONG) -- User data like GA_UserData
DTA_FrameInfo (struct FrameInfo *) -- RESERVED
DTA_SelectDomain (struct IBox *) -- Select area's box, in absolute
window/requester/screen coordinates.
Applicability for applications is (G),
Applicability for subclasses is (SG).
DTA_TotalPVert (LONG) - Object's page size, in pixels
Applicability for applications is (G),
Applicability for subclasses is (G).
DTA_TotalPHoriz (LONG) - Object's page size, in pixels
Applicability for applications is (G),
Applicability for subclasses is (G).
DTA_NominalVert (LONG) - nominal height of object
Applicability for applications is (G),
Applicability for subclasses is (SG).
DTA_NominalHoriz (LONG) - nominal height of object
Applicability for applications is (G),
Applicability for subclasses is (SG).
/* Printing attributes */
The printing attributes are only used in conjunction with DTM_PRINT.
DTA_DestCols (LONG) - Destination X width
DTA_DestRows (LONG) - Destination Y height
DTA_Special (UWORD) - Option flags, see <devices/printer.h>
DTA_RastPort (struct RastPort *) - RastPort to use when printing.
NOTES
SEE ALSO
BUGS
datatypesclass/DTM_ABORTPRINT datatypesclass/DTM_ABORTPRINT
NAME
DTM_ABORTPRINT -- Aborts a pending print job
FUNCTION
This methods aborts a pendig print job.
Note that you must wait for the print process before
you can dispose the object. DisposeDTObject will wait until
the job exists.
RESULT
Returns 0 for now.
datatypesclass/DTM_ASYNCLAYOUT datatypesclass/DTM_ASYNCLAYOUT
NAME
DTM_ASYNCLAYOUT -- Asyncronous layout
FUNCTION
This method offloads time intensive things like text layout or
remapping from input.device on a sepeate process. This
method will only be used when the "AsyncLayoutDeamon" process
was invoked by DoAsyncLayout in the GM_LAYLOUT method.
RESULT
Non-zero for success, 0 for failure.
SEE ALSO
GM_LAYOUT,
datatypes.library/DoAsyncLayout
datatypesclass/DTM_FRAMEBOX datatypesclass/DTM_FRAMEBOX
NAME
DTM_FRAMEBOX -- Inquire what environment an object requires
FUNCTION
This method is to inquire what environment an object requires,
which depends on the source data; an object like a picture
or an animation maybe requires special things like a HAM screen for
HAM pictures or HAM animations.
If the FRAMEF_SPECIFY flag is set in the msg, the method tells
the object to prepare itself to enter the described environment.
datatypesclass does __currently__ do nothing on the FrameInfo
structure given, but must be called when an object receives a
DTM_FRAMEBOX method.
If the DTA_SourceType attribute equals to DTST_CLIPBOARD,
the clipboard handle will be closed here.
RESULT
Nothing returned.
datatypesclass/DTM_PRINT datatypesclass/DTM_PRINT
NAME
DTM_PRINT -- print object
FUNCTION
This method should print the contents of the object.
This method should be superset by the given subclass.
datatypesclass returns PDERR_CANCEL and sets IoErr to
ERROR_NOT_IMPLEMENTED.
ATTRIBUTES
A subclass may recognise one of the following attribues:
DTA_DestCols (LONG) - Destination X width, see <devices/printer.h>
DTA_DestRows (LONG) - Destination Y height, see <devices/printer.h>
DTA_Special (UWORD) - Option flags,
see <devices/printer.h>, SPECIAL_#? defines.
DTA_RastPort (struct RastPort *) RastPort to use when printing. (V40)
Must only be used of the datatypes object is used like
an image (e.g. in a DTM_OBTAINDRAWINFO/DTM_DRAW/
DTM_RELEASEDRAWINFO cycle). The rastport given should be the same
passed to DTM_DRAW.
This tag MUST not be used if the object is used as a gadget.
Other tags are subclass-specific:
For example, a animation.datatype (V42) subclass may recognise
ADTA_Frame (ULONG) - start frame to print
ADTA_Frames (ULONG) - number of frames to print.
and so on.
NOTE
This method is normally asyncrony launched using PrintDTObjectA.
The async print process will notify the return value of this
method as DTA_PrinterStatus.
RESULT
Returns PDERR_CANCEL and (result2 == ERROR_NOT_IMPLEMENTED).
SEE ALSO
datatypes.library/PrintDTObjectA,
<devices/printer.h>
datatypesclass/DTM_PROCLAYOUT datatypesclass/DTM_PROCLAYOUT
NAME
DTM_PROCLAYOUT -- Layout datatypesclass object
FUNCTION
This method should be treated like DTM_ASYNCLAYOUT. The only
difference is that DTM_ASYNCLAYOUT is triggered by the
GM_LAYOUT method, which calls the DoAsyncLayout function
("AsyncLayoutDeamon" process launched by it), DTM_PROCLAYOUT is
triggered by the application manually.
The DTM_PROCLAYOUT method replaces both GM_LAYOUT and DTM_ASYNCLAYOUT
.
DTM_PROCLAYOUT should not be triggered when the object will be added
into an window/requester using AddDTObject.
This method is exacly the same as datatypesclass/GM_LAYOUT.
RESULT
See GM_LAYOUT
datatypesclass/DTM_REMOVEDTOBJECT datatypesclass/DTM_REMOVEDTOBJECT
NAME
DTM_REMOVEDTOBJECT -- Remove a dt object from a window/requester
FUNCTION
Releases resources obtained during GM_LAYOUT/DTM_PROCLAYOUT.
This method MUST be passed to datatypesclass if an object receives
a DTM_REMOVEDTOBJECT msg.
RESULT
GM_LAYOUT, DTM_PROCLAYOUT
datatypesclass/DTM_WRITE datatypesclass/DTM_WRITE
NAME
DTM_WRITE -- Write object to file
FUNCTION
This method should write the contens of an object to a file.
This method should be superset by the given subclass.
datatypesclass returns 0 and sets IoErr to ERROR_NOT_IMPLEMENTED.
ATTRIBUTES
Class specific.
For example, a animation.datatype subclass may recognise
ADTA_Frame (ULONG) - start frame to save
ADTA_Frames (ULONG) - number of frames to save.
and so on.
NOTE
If a datatypesclass has the version 45 or higher, a NULL
file handle must be a NOP. This was introduced to check if
a particular subclass supports DTM_WRITE with DTWM_RAW (local
format).
RESULT
Returns 0 and (result2 == ERROR_NOT_IMPLEMENTED).
SEE ALSO
datatypesclass/GM_DOMAIN datatypesclass/GM_DOMAIN
NAME
GM_DOMAIN -- obtain the domain of an datatypes object (V45)
FUNCTION
The GM_DOMAIN method is used to obtain the domain of a
datatypesclass object. datatypesclass requires an object
to process this method.
Subclasses may require a RastPort pointer in gpd_RPort with the
correct font attributes.
datatypesclass supports the gpd_Which == GDOMAIN_MINIMUM,
GDOMAIN_NOMINAL and GDOMAIN_MAXIMUM.
If the gpd_GInfo (GadgetInfo) is valid (non-NULL), the
(gpd_Domain . Left) and (gpd_Domain . Top) fields will be filled based
on the values set with GA_Left/GA_Top/GA_RelRight/GA_RelBottom.
otherwise these two fields are 0 as noted below.
If all attributes got are 0, GDOMAIN_NOMINAL and GDOMAIN_MAXIMUM
fall back to width=600, height=200. This fallback dimensions may vary
from case to case.
GDOMAIN_MINIMUM returns 0,0,0,0
GDOMAIN_NOMINAL returns 0,0,DTA_NominalHoriz,DTA_NominalVert
If the DTA_NominalHoriz is 0,
(DTA_TotalHoriz * MAX( DTA_HorizUnit, 1 )) is used instead.
If the DTA_NominalVert is 0,
(DTA_TotalVert * MAX( DTA_VertUnit, 1 )) is used instead.
GDOMAIN_MAXIMUM returns 0,0,
(DTA_TotalHoriz * MAX( DTA_HorizUnit, 1 )),
(DTA_TotalVert * MAX( DTA_VertUnit, 1 )).
ATTRIBUTES
datatypesclass does ignore any args, but subclasses may depend on
some of these tags:
DTA_TextAttr (struct TextAttr *) - Default text font used in object
NOTE
Subclasses may superset some of the GDOMAIN_#? cases above,
but MUST pass unknown or unsupported cases to datatypesclass.
TODO
Replace the hard-coded fallback domain (w=600, h=200) with
an more smarter way...
RESULT
Returns TRUE and fills in the gpd_Domain field if successfull,
FALSE otherwise.
SEE ALSO
datatypes.library/DoDTDomain
datatypesclass/GM_GOACTIVE datatypesclass/GM_GOACTIVE
NAME
GM_GOACTIVE -- prepare the object to be activated
FUNCTION
Prepare the object to be activated.
This method falls through to GM_HANDLEINPUT
RESULT
See GM_HANDLEINPUT
datatypesclass/GM_GOINACTIVE datatypesclass/GM_GOINACTIVE
NAME
GM_GOINACTIVE -- Deactivate object
FUNCTION
RESULT
datatypesclass/GM_HANDLEINPUT datatypesclass/GM_HANDLEINPUT
NAME
GM_HANDLEINPUT -- handle input
FUNCTION
RESULT
datatypesclass/GM_HITTEST datatypesclass/GM_HITTEST
NAME
GM_HITTEST -- Test if the object has been hit
FUNCTION
The GM_HITTEST queries the object if the given coordinates hits
the datatypesclass object.
RESULT
Returns evertimes GMR_GADGETHIT.
datatypesclass/GM_LAYOUT datatypesclass/GM_LAYOUT
NAME
GM_LAYOUT -- Layout datatypesclass object
FUNCTION
Layout datatypesclass object.
This method updates the DTA_Domain box to reflect the absolute
dimensions of the gadget's domain box and updates the DTA_TotalPVert
and DTA_TotalPHoriz attributes.
Gadget relativity is fully supported.
After all this method falls througth to the DTM_FRAMEBOX method.
RESULT
datatypesclass/OM_DISPOSE datatypesclass/OM_DISPOSE
NAME
OM_DISPOSE -- Dispose datatypesclass instance
FUNCTION
This method destroys a datatypesclass object, freeing all resources
obtained by it.
This method preserves the IoErr error value.
RESULT
Returns the return code from superclass.
datatypesclass/OM_GET datatypesclass/OM_GET
NAME
OM_GET -- Get a datatypesclass attribute
FUNCTION
The OM_GET method is used to obtain the value of a datatypesclass
attribute.
If the attribute to get not recognizes by datatypesclass, the msg
is passes to superclass (gadgetclass).
ATTRIBUTES
DTA_TopVert (LONG) - Returns (dtsi -> si_TopVert)
DTA_VisibleVert (LONG) - Returns (dtsi -> si_VisVert)
DTA_TotalVert (LONG) - Returns (dtsi -> si_TotVert)
DTA_VertUnit (LONG) - Returns (dtsi -> si_VertUnit)
DTA_TopHoriz (LONG) - Returns (dtsi -> si_TopHoriz)
DTA_VisibleHoriz (LONG) - Returns (dtsi -> si_VisHoriz)
DTA_TotalHoriz (LONG) - Returns (dtsi -> si_TotHoriz)
DTA_HorizUnit (LONG) - Returns (dtsi -> si_HorizUnit)
DTA_PrinterProc (struct Process *) - PRIVATE !
DTA_LayoutProc (struct Process *) - PRIVATE !
DTA_Name (STRPTR) - File name set in OM_NEW
DTA_SourceType (ULONG) - Source handle type of DTA_Handle,
one of the DTST_#? identifies.
DTA_Handle (APTR) - Handle, as opened by datatypesclass/OM_NEW
The following table shows the type of handle returned
(the "DTF_ type"-column below means which type (DTF_BINARY,
DTF_ASCII, DTF_IFF or DTF_MISC your datatype belongs to; e.g. an
IFF datatype will only get IFF Handles etc.):
DTA_SourceType|DTF_ type |Handle type
================================================================
DTST_RAM |DTF_#? |-- Must be NULL.
--------------+----------+--------------------------------------
DTST_FILE |DTF_BINARY|(BPTR), like returned from Open
|DTF_ASCII |(BPTR), like returned from Open
|DTF_IFF |(struct IFFHandle *), iffparse.library
| | handle
|DTF_MISC |(BPTR), like returned from Lock
--------------+----------+--------------------------------------
DTST_CLIPBOARD|DTF_IFF |(struct IFFHandle *), iffparse.library
| | handle
--------------+----------+--------------------------------------
DTST_HOTLINK |DTF_#? |NOT IMPLEMENTED YET
--------------+----------+--------------------------------------
DTA_DataType (struct DataType *) - Returns DataType structure.
May be NULL !
DTA_Domain (struct IBox *) - Returns ptr to struct IBox.
This is equal to the GA_Left/GA_Top/GA_Width/GA_Height box,
translated into window/requester coordinates, even if the
GA_#? identifers are relative (GA_Rel#?).
DTA_ObjName (STRPTR) - Source data name
DTA_ObjAuthor (STRPTR) - Source data author
DTA_ObjAnnotatiom (STRPTR) - Source data annotation
DTA_ObjCopyright (STRPTR) - Source data copyright
DTA_ObjVersion (STRPTR) - Source data version
DTA_ObjectID (ULONG) - Object ID
DTA_UserData (ULONG) - User data, not touched by datatypesclass
or a subclass (like GA_UserData).
DTA_FrameInfo - (struct FrameInfo *)
DTA_SelectDomain (struct IBox *) - Box of selected area in
window/requester coordinates. Returns NULL is there is
no selected area.
DTA_TotalPVert (LONG) - Page height, e.g.
((dtsi -> si_VertUnit) * (dtsi -> si_TotVert)) or
(DTA_Domain . Height) if VertUnit is 0.
DTA_TotalPHoriz (LONG) - Page width, e.g.
((dtsi -> si_HorizUnit) * (dtsi -> si_TotHoriz)) or
(DTA_Domain . Width) if HorizUnit is 0.
DTA_NominalVert (LONG) - Nominal object height.
DTA_NominalHoriz (LONG) - Nominal object width.
DTA_Data (Object *) - The object itself (V45).
A NULL return indicates that the object hasn't loaded
all data yet (progressive loading, see DTA_Progressive).
(a subclass has to superset OM_GET to set this tag
to NULL, datatypesclass will everytimes return the "Object"
itself).
BUGS
None known.
RESULT
Returns TRUE if the datatypesclass supports this attribute,
returns the superclass (gadgetclass) return value otherwise.
datatypesclass/OM_NEW datatypesclass/OM_NEW
NAME
OM_NEW -- Create a datatypesclass object.
FUNCTION
The OM_NEW method is used to create an instance of the datatypesclass
class. This method is passed to the superclass first.
After this, datatypesclass opens a handle. The type of handle
will be selected based on type of input data the class can process
(e.g. an IFF DataType will get only IFFHandles, to make things
easier).
This class cannot be create objects without having a subclass
("abstract" class). Starting with V45, any attempt to create a
object of datatypesclass will be rejected by this method; only
object's of one of it's subclasses are allowed.
The following table shows the type of handle returned (the
"DTF_ type"-column below means which type (DTF_BINARY, DTF_ASCII,
DTF_IFF or DTF_MISC your datatype belongs to)
(the handle must be obtained using GetDTAttrsA):
DTA_SourceType|DTF_ type |Handle type
================================================================
DTST_RAM |DTF_#? |-- Must be NULL.
--------------+----------+--------------------------------------
DTST_FILE |DTF_BINARY|(BPTR), like returned from Open
|DTF_ASCII |(BPTR), like returned from Open
|DTF_IFF |(struct IFFHandle *), iffparse.library
| | handle
|DTF_MISC |(BPTR), like returned from Lock
--------------+----------+--------------------------------------
DTST_CLIPBOARD|DTF_IFF |(struct IFFHandle *), iffparse.library
| | handle
--------------+----------+--------------------------------------
DTST_HOTLINK |DTF_#? |NOT IMPLEMENTED YET
--------------+----------+--------------------------------------
ATTRIBUTES
The following attributes can be specified at creation time:
BUGS
RESULT
If the object was created a pointer to the object is returned,
otherwise NULL is returned.
datatypesclass/OM_SET datatypesclass/OM_SET
NAME
OM_SET -- Set datatypesclass attributes
FUNCTION
The OM_SET method is used to set datatypesclass attributes.
Does bounds checking on the DTSpecialInfo's fields si_TopVert,
si_VisVert, si_TotVert, si_TopHoriz, si_VisHoriz and si_TotHoriz
and notifies changes.
ATTRIBUTES
DTA_TopVert (LONG) - current vertical position.
Copied into (dtsi -> si_TopVert); this method returns TRUE for
a value change.
DTA_VisibleVert (LONG) - visible area
Copied into (dtsi -> si_VisVert); this method returns TRUE for
a value change.
DTA_TotalVert (LONG) - total vertical size
Copied into (dtsi -> si_TotVert); this method returns TRUE for
a value change.
DTA_VertUnit (LONG) - vertical unit
Size of one unit in which the DTA_(Top|Visible|Total)Vert
attributes counts.
DTA_TopHoriz (LONG) - current horizontal position.
Copied into (dtsi -> si_TopHoriz); this method returns TRUE for
a value change.
DTA_VisibleHoriz (LONG) - visible area
Copied into (dtsi -> si_VisHoriz); this method returns TRUE for
a value change.
DTA_TotalHoriz (LONG) - total horizontal size
Copied into (dtsi -> si_TotHoriz); this method returns TRUE for
a value change.
DTA_HorizUnit (LONG) - horizontal unit
Size of one unit in which the DTA_(Top|Visible|Total)Horiz
attributes counts.
DTA_PrinterProc (struct Process *) -- PRIVATE !
DTA_LayoutProc (struct Process *) -- PRIVATE !
DTA_ObjName (STRPTR) - name of object source data
The string given will be copied into an internal buffer.
DTA_ObjAuthor (STRPTR) - source data author
The string given will be copied into an internal buffer.
DTA_ObjAnnotation (STRPTR) - source data annotation
The string given will be copied into an internal buffer.
DTA_ObjCopyright (STRPTR) - source data copyright
The string given will be copied into an internal buffer.
DTA_ObjVersion (STRPTR) - source data copyright
The string given will be copied into an internal buffer.
DTA_ObjectID (ULONG) - object id
DTA_UserData (ULONG) - User data, not touched by datatypesclass
or a subclass (like GA_UserData).
DTA_SelectDomain (struct IBox *) - selected area box,
in window/requester coordinates.
NULL is a valid input (V45).
DTA_NominalVert (LONG) - nominal vertical size (height)
DTA_NominalHoriz (LONG) - nominal vertical size (width)
BUGS
None kown.
TODO
Changes of the GA_Left/GA_Top/GA_Width/GA_Height
RESULT
If any of the DTA_(Top|Visbible|Total)(Vert|Horiz)-attributes
has been changes, this method returns non-zero (change),
the return value from superclass (gadgetclass) otherwise.
datatypesclass/OM_UPDATE datatypesclass/OM_UPDATE
NAME
OM_UPDATE -- Update datatypesclass attributes
FUNCTION
The OM_UPDATE method is used to update datatypesclass attributes;
it falls througth to OM_SET.
Starting with V45, OM_UPDATE will explicitly call ICM_CHECKLOOP
to avoid notify loops.
ATTRIBUTES
See OM_SET
RESULT
See OM_SET