AddDTObject
SYNOPSIS
AddDTObject(win, req, obj, pos)
LONG AddDTObject(struct Window*, struct Requester *, Object *, LONG);
DESCRIPTION
Add an object to the window 'win' or requester 'req' at the position
in the gadget list specified by the 'pos' argument
INPUTS
win -- window the object should be added to; may be NULL in which case
nothing is done
req -- requester the object should be added to
obj -- the object to add; may be NULL in which case nothing is done
pos -- the position of the object in the list
RESULT
The position where the object was added (may be different from what
you asked for
NOTES
The object will receice a GM_LAYOUT message with the gpl_Initial field
set to 1 when the object is added.
SEE ALSO
CopyDTMethods
SYNOPSIS
CopyDTMethods(methods, include, exclude)
ULONG * CopyDTMethods(ULONG *, ULONG *, ULONG *);
DESCRIPTION
Copy and modify an array of methods. This is used by subclass implementors
who want to add supported methods to an existing class
INPUTS
methods -- array of methods; may be NULL
include -- array of methods to include terminated with ~0UL; may be NULL
method -- array of methods to exclude terminated with ~0UL; may be NULL
RESULT
The new array of methods or NULL if something went wrong (like out of
memory
INTERNALS
When a method is specified both in the 'include' and the 'exclude',
it will be included.
HISTORY
2.8.99 SDuvan implemented
SEE ALSO
CopyDTTriggerMethods
SYNOPSIS
CopyDTTriggerMethods(methods, include, exclude)
struct DTMethod * CopyDTTriggerMethods(struct DTMethod *, struct DTMethod *, struct DTMethod *);
DESCRIPTION
Copy and modify an array of DTMethod:s. This is used by subclass
implementors who want to add supported methods to an existing class
INPUTS
methods -- array of methods; may be NULL
include -- array of methods to include terminated with ~0UL; may be NULL
method -- array of methods to exclude terminated with ~0UL; may be NULL
the dtm_Command and dtm_Method fields may have the options
described in the FindTriggerMethod to filter out the given
entries
RESULT
The new array of methods or NULL if something went wrong (like out of
memory
NOTES
dtm_Label and dtm_Command must be valid as long as the object exists as
they are not copied.
A subclass that implment DTM_TRIGGER must send unknown trigger
methods to its superclass.
HISTORY
2.8.99 SDuvan implemented
SEE ALSO
DisposeDTObject
SYNOPSIS
DisposeDTObject(o)
void DisposeDTObject(Object *);
DESCRIPTION
Dispose a data type object obtained by NewDTObjectA
INPUTS
o -- The data type object to dispose of; may be NULL
SEE ALSO
DoAsyncLayout
SYNOPSIS
DoAsyncLayout(object, gpl)
ULONG DoAsyncLayout(Object *, struct gpLayout *);
DESCRIPTION
Perform an object's DTM_ASYNCLAYOUT method -- doing it asynchronously
off loads the input.device. The method should exit when a SIGBREAK_CTRL_C
is received; this signal means that the data is obsolete and the the
method will be called again
INPUTS
object -- pointer to data type object
gpl -- gpLayout message pointer
DoDTDomainA
SYNOPSIS
DoDTDomainA(o, win, req, rport, which, domain, attrs)
ULONG DoDTDomainA(Object *, struct Window*, struct Requester *, struct RastPort*, ULONG, struct IBox*, struct TagItem *);
DESCRIPTION
Obtain the maximum/minimum/nominal domains of a data type object
INPUTS
o -- data type object in question
win -- window that the object is attached to
req -- requester the object is attached to
rport -- rastport; used for domain calculations
which -- the domain to obtain (GDOMAIN_, see <intuition/gadgetclass.h>
domain -- the result will be put here
attrs -- additional attributes (subclass specific
RESULT
The return value of GM_DOMAIN or 0 if an error occurred. The 'domain'
IBox will be filled with the requested values as a side effect
NOTES
This function requires an object to perform the GM_DOMAIN method. To
achieve similar results without an object, you must use CoerceMethodA()
manually.
HISTORY
7.8.99 SDuvan implemented
SEE ALSO
<intuition/gadgetclass.h>
DoDTMethodA
SYNOPSIS
DoDTMethodA(o, win, req, msg)
ULONG DoDTMethodA(Object *, struct Window*, struct Requester *, Msg);
DESCRIPTION
Perform a specific datatypes methodl
INPUTS
o -- pointer to data type object
win -- window the object is attached to
req -- requester the object is attached to
msg -- the message to send to the object
RESULT
The value returned by the specified method
SEE ALSO
intuition.library/DoGadgetMethod
DrawBox
DESCRIPTION
datatypes.library/DrawBox
*
* NAME
* DrawBox - draw a box for area marking
*
* SYNOPSIS
*
* FUNCTION
*
* INPUTS
*
* RETURNS
*
* EXAMPLE
*
* SEE ALSO
DrawDTObjectA
SYNOPSIS
DrawDTObjectA(rp, o, x, y, w, h, th, tv, attrs)
LONG DrawDTObjectA(struct RastPort *, Object*, LONG, LONG, LONG, LONG, LONG, LONG, struct TagItem*);
DESCRIPTION
Draw a data type object into a RastPort. You must have successfully
called ObtainDTDrawInfoA before calling this function; it invokes the
object's DTM_DRAW method
INPUTS
rp -- pointer to the RastPort to draw the object into
o -- pointer to the data type object to draw
x -- left edge of drawing area
y -- top edge of drawing area
w -- width of drawing area
h -- height of drawing area
th -- horizontal top in units
tv -- vertical top in units
attrs -- additional attributes
RESULT
TRUE if rendering went OK, FALSE if failure
NOTES
The RastPort in question must support clipping, i.e. have a valid
layer structure attached to it; if not, some datatypes can't draw
and FALSE will be returned.
INTERNALS
The type is stated to be LONG in the original docs even if the return
value is really BOOL.
HISTORY
29.7.99 SDuvan implemented
TAGS
ADTA_Frame for animationclass objects (selects the frame that should be
drawn.
SEE ALSO
FindMethod
SYNOPSIS
FindMethod(methods, searchmethodid)
ULONG * FindMethod(ULONG *, ULONG);
DESCRIPTION
Search for a specific method in a array of methods
INPUTS
methods -- array of methods; may be NULL
searchmethodid -- method to search for
RESULT
Pointer to method table entry or NULL if the method wasn't found
HISTORY
2.8.99 SDuvan implemented
SEE ALSO
FindToolNodeA
SYNOPSIS
FindToolNodeA(toollist, attrs)
struct ToolNode * FindToolNodeA(struct List*, struct TagItem *);
DESCRIPTION
Search for a specific tool in a list of given tool nodes
INPUTS
toollist -- a list or a struct ToolNode * (which will be skipped) to
search in; may be NULL.
attrs -- search tags; if NULL, the result of the function will
simply be the following node
RESULT
A pointer to a ToolNode describing the search result (NULL for failure
NOTES
The entries in dt->dtn_ToolList are valid as long as a lock is kept on
the data type 'dt' (ObtainDataTypeA() or LockDataType()).
HISTORY
7.8.99 SDuvan implemented
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
SEE ALSO
FindTriggerMethod
SYNOPSIS
FindTriggerMethod(methods, command, method)
struct DTMethod * FindTriggerMethod(struct DTMethod *, STRPTR, ULONG);
DESCRIPTION
Search for a specific trigger method in a array of trigger methods (check
if either 'command' or 'method' matches
INPUTS
methods -- array of trigger methods; may be NULL
command -- name of trigger method (may be NULL; if so, 'command'
is not matched against)
method -- id of trigger method to search for (may be ~0; if so, don't
match against 'method
RESULT
Pointer to trigger method table entry (struct DTMethod *) or NULL if the
method wasn't found
HISTORY
2.8.99 SDuvan implemented
SEE ALSO
FreeDTMethods
SYNOPSIS
FreeDTMethods(methods)
VOID FreeDTMethods(APTR);
DESCRIPTION
Free array obtained from CopyDTMethods() or CopyDTTriggerMethods
INPUTS
methods -- array of methods; may be NULL
HISTORY
2.8.99 SDuvan implemented
SEE ALSO
GetDTAttrsA
SYNOPSIS
GetDTAttrsA(o, attrs)
ULONG GetDTAttrsA(Object *, struct TagItem *);
DESCRIPTION
Get the attributes of a specific data type object
INPUTS
o -- pointer to a data type object; may be NULL
attrs -- the attributes to get terminated with TAG_DONE; each Tag's
data element should contain the address of the respective
storage element; may be NULL
RESULT
The number of attributes obtained
SEE ALSO
GetDTMethods
SYNOPSIS
GetDTMethods(object)
ULONG * GetDTMethods(Object *);
DESCRIPTION
Get a list of the methods an object supports
INPUTS
object -- pointer to a data type object
RESULT
Pointer to a ULONG array which is terminated ~0; the array is only
valid until the object is disposed of
SEE ALSO
GetDTString
SYNOPSIS
GetDTString(id)
STRPTR GetDTString(ULONG);
DESCRIPTION
Get a pointer to a localized datatypes string
INPUTS
id -- ID of the string to get
RESULT
Pointer to a NULL terminated string
GetDTTriggerMethodDataFlags
SYNOPSIS
GetDTTriggerMethodDataFlags(method)
ULONG GetDTTriggerMethodDataFlags(ULONG);
DESCRIPTION
Get the kind of data that may 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 the STMF_METHOD_MASK value) with one of the STMD_
identifiers.
STMD_VOID -- stt_Data must be NULL
STMD_ULONG -- stt_Data contains an unsigned value
STMD_STRPTR -- stt_Data is a pointer to a string
STMD_TAGLIST -- stt_Data points to an array of struct TagItem terminated
with TAG_DONE
The trigger methods below STM_USER are explicitly handled as described in
<datatypes/datatypesclass.h>
INPUTS
method -- dtt_Method ID from struct DTMethod
RESULT
One of the STMD_ identifiers defined in <datatypes/datatypesclass.h>
HISTORY
5.8.99 SDuvan implemented
SEE ALSO
GetDTTriggerMethods
SYNOPSIS
GetDTTriggerMethods(object)
struct DTMethods * GetDTTriggerMethods(Object *);
DESCRIPTION
Get a list of the trigger methods an object supports
INPUTS
object -- pointer to a data type object
RESULT
A pointer to a STM_DONE terminated DTMethod list. This list in only valid
until the object is disposed of
NOTES
Some trigger methods requires an argument (calling these with a NULL
argument is wrong). Use GetDTTriggerMethodDataFlags() to obtain the
type of the requested argument.
EXAMPLE
To call the specific method, do the following:
DoMethod(object, DTM_TRIGGER, myMethod
SEE ALSO
LaunchToolA
SYNOPSIS
LaunchToolA(tool, project, attrs)
ULONG LaunchToolA(struct Tool *, STRPTR, struct TagItem *);
DESCRIPTION
Launch an application with a particular project
INPUTS
tool -- tool to use (may be NULL in which case this function
returns 0)
project -- name of the project to execute or NULL
attrs -- additional attributes
RESULT
Zero for failure, non-zero otherwise
HISTORY
SDuvan 17.12.2000 -- basic implementation
TAGS
NP_Priority (BYTE) -- priority of the launched tool (default is the
priority of the currect process except for
Workbench applications where the default priority
is 0 if not overridden by the TOOLPRI tooltype).
NP_Synchronous (BOOL) -- don't return until lauched application process
finishes (defaults to FALSE).
SEE ALSO
LockDataType
SYNOPSIS
LockDataType(dt)
VOID LockDataType(struct DataType *);
DESCRIPTION
Lock a DataType structure obtained from ObtainDataTypeA() or a data type
object (DTA_DataType
INPUTS
dt -- DataType structure; may be NULL
NOTES
Calls to LockDataType() and ObtainDataTypeA() must have a corresponding
ReleaseDataType() call or else problems will arise.
HISTORY
2.8.99 SDuvan implemented
SEE ALSO
NewDTObjectA
SYNOPSIS
NewDTObjectA(name, attrs)
Object * NewDTObjectA(APTR, struct TagItem *);
DESCRIPTION
Create a data type object from a BOOPSI class
INPUTS
name -- name of the data source; generally an existing file name
attrs -- pointer to a TagList specifying additional arguments
RESULT
A BOOPSI object. This may be used in different contexts such as a gadget
or image. NULL indicates failure -- in that case IoErr() gives more
information:
ERROR_REQUIRED_ARG_MISSING -- A required attribute wasn't specified.
ERROR_BAD_NUMBER -- The group ID specified was invalid.
ERROR_OBJECT_WRONG_TYPE -- Object data type doesn't match DTA_GroupID
NOTES
This function invokes the method OM_NEW for the specified class.
The object should (eventually) be freed by DisposeDTObject() when no
longer needed.
TAGS
DTA_SourceType -- The type of source data (defaults to DTST_FILE).
If the source is the clipboard the name field
contains the numeric clipboard unit. DTST_MEMORY
ignores the name field and DTA_Handle.
DTA_SourceAddress and DTA_SourceSize specify the
data buffer for DTST_MEMORY.
DTA_Handle -- Can be used instead of the 'name' field. If the
source is DTST_FILE, this must be a valid FileHandle;
must be a valid IFFHandle if source is DTST_CLIPBOARD.
Ignored for DTST_MEMORY.
DTA_DataType -- The class of the data. Data is a pointer to a valid
DataType; only used when creating a new object that
doens't have any source data.
DTA_GroupID -- If the object isn't of this type, fail with an IoErr()
of ERROR_OBJECT_WRONG_TYPE.
GA_Left
GA_RelRight
GA_Top
GA_RelBottom
GA_Width
GA_RelWidth
GA_Height
GA_RelHeight -- Specify the position of the object relative to the
window.
GA_ID -- ID of the object.
GA_UserData -- Application specific data for the object.
GA_Previous -- Previous object / gadget in the list.
SEE ALSO
ObtainDTDrawInfoA
SYNOPSIS
ObtainDTDrawInfoA(o, attrs)
APTR ObtainDTDrawInfoA(Object *, struct TagItem *);
DESCRIPTION
Prepare a data type object for drawing into a RastPort; this function
will send the DTM_OBTAINDRAWINFO method the object using an opSet
message
INPUTS
o -- pointer to the data type object to obtain the drawinfo for;
may be NULL in which case nothing is done
attrs -- additional attributes
RESULT
A private handle that must be passed to ReleaseDTDrawInfo when the
application is done drawing the object, or NULL if failure
HISTORY
29.8.99 SDuvan implemented
TAGS
PDTA_Screen -- for pictureclass objects
ADTA_Screen -- for animationclass objects
SEE ALSO
PrintDTObjectA
SYNOPSIS
PrintDTObjectA(object, window, requester, msg)
ULONG PrintDTObjectA(Object *, struct Window*, struct Requester *, struct dtPrint *);
DESCRIPTION
Perform an object's DTM_PRINT method in an asynchronous manner
INPUTS
object -- pointer to the data type object
window -- pointer to the window the object has been added to
requester -- pointer to the requester the object has been added to
RESULT
TRUE on success, FALSE otherwise
NOTES
When an application has called PrintDTObjectA() it must not touch
the printerIO union until a IDCMP_IDCMPUPDATE is received which
contains the DTA_PrinterStatus tag.
To abort a print, send the DTM_ABORTPRINT method to the object.
This will signal the print process with a SIGBREAK_CTRL_C.
RefreshDTObjectA
SYNOPSIS
RefreshDTObjectA(object, window, req, attrs)
void RefreshDTObjectA(Object *, struct Window*, struct Requester *, struct TagItem *);
DESCRIPTION
Refresh a specified object sending the GM_RENDER message to the object
INPUTS
object -- pointer to the data type object to refresh; may be NULL
window -- pointer to the window; may be NULL
req -- must be NULL
attrs -- additional attributes (currently none defined
SEE ALSO
ReleaseDTDrawInfo
SYNOPSIS
ReleaseDTDrawInfo(o, handle)
VOID ReleaseDTDrawInfo(Object *, APTR);
DESCRIPTION
Release the handle obtained from ObtainDTDrawInfoA(); invokes the object's
DTM_RELEASEDRAWINFO method sending the dtReleaseDrawInfo message
INPUTS
o -- pointer to the data type object the drawinfo of which to
release; may be NULL
handle -- handle got from ObtainDTDrawInfoA
RESULT
A private handle that must be passed to ReleaseDTDrawInfo when the
application is done drawing the object, or NULL if failure
HISTORY
29.8.99 SDuvan implemented
TAGS
PDTA_Screen -- for pictureclass objects
ADTA_Screen -- for animationclass objects
SEE ALSO
ReleaseDataType
SYNOPSIS
ReleaseDataType(dt)
VOID ReleaseDataType(struct DataType *);
DESCRIPTION
Release a DataType structure aquired by ObtainDataTypeA
INPUTS
dt -- DataType structure as returned by ObtainDataTypeA(); NULL is
a valid input
SEE ALSO
RemoveDTObject
SYNOPSIS
RemoveDTObject(window, object)
LONG RemoveDTObject(struct Window *, Object*);
DESCRIPTION
Remove an object from the specified window's object list; this will wait
until the AsyncLayout process is ready. The object will receive a message
of type DTM_REMOVEDTOBJECT as a sign of it having been removed
INPUTS
window -- pointer to the window in question
object -- pointer to the object to remove
RESULT
The position of the object in the list before it was removed; if the
object wasn't found -1 is returned
SEE ALSO
SaveDTObjectA
SYNOPSIS
SaveDTObjectA(o, win, req, file, mode, saveicon, attrs)
ULONG SaveDTObjectA(Object *, struct Window*, struct Requester *, STRPTR, ULONG, BOOL, struct TagItem *);
DESCRIPTION
Save the contents of an object to a file using DTM_WRITE
INPUTS
o -- data type object to write to a file
win -- window the object is attached to
req -- requester the object is attached to
file -- name of the file to save the object to
mode -- save mode (RAW, IFF etc.), one of the DTWM_ identifiers
saveicon -- should an icon be saved together with the file
attrs -- additional attributes (these are subclass specific
RESULT
The return value of DTM_WRITE
NOTES
If DTM_WRITE returns 0, the file will be deleted.
HISTORY
6.8.99 SDuvan implemented
SetAttributes
DESCRIPTION
datatypes.library/SetAttributes
*
* NAME
* SetAttributes - set a DTObject's attributes given an opSet structure
*
* SYNOPSIS
*
* FUNCTION
*
* INPUTS
*
* RETURNS
*
* EXAMPLE
*
* SEE ALSO
SetDTAttrsA
SYNOPSIS
SetDTAttrsA(o, win, req, attrs)
ULONG SetDTAttrsA(Object *, struct Window*, struct Requester *, struct TagItem *);
DESCRIPTION
Set the attributes of a data type object
INPUTS
o -- pointer to the data type object the attributes of which to set
win -- window that the object has been added to
attrs -- attributes to set (terminated with TAG_DONE)
tags are specified in <datatypes/datatypesclass.h>
SEE ALSO
GetDTAttrsAintuition.library/SetGadghetAttrsA<datatypes/datatypesclass.h>
StartDragSelect
SYNOPSIS
StartDragSelect(o)
ULONG StartDragSelect(Object *);
DESCRIPTION
Start drag-selection by the user; the drag selection will only start
if the object in question supports DTM_SELECT, is in a window or
requester and no layout-process is working on the object
INPUTS
o -- data type object in question; may be NULL
RESULT
TRUE if all went OK, FALSE otherwise. If FALSE, IoErr() gives further
information:
ERROR_ACTION_NOT_KNOWN -- the object doesn't support DTM_SELECT
ERROR_OBJECT_IN_USE -- the object is currently occupied
HISTORY
6.8.99 SDuvan implemented