@database english_gtdrag @index index @node main "gtdrag - Documentation" @{b}gtdrag - Version 2 Revision 7, 15.12.1996@{ub} This package is copyrighted ©1996 by @{"Axel Dörfler" link author} All rights reserved. @{"Copyright notice " link copyright} @{"Introduction " link intro} @{"System requirements" link required} @{"Functions " link funcs} @{"Author " link author} @{"Credits " link credits} @{"Release Notes " link release} @{"Known Bugs " link bugs} @{"To do " link todo} This is the final release of the package. This doesn't mean that it has implemented all planned features yet, but the API will stay compatible with upcoming releases. @endnode @node copyright "gtdrag - Copyright notice" The package is ©1996 by @{"Axel Dörfler" link author}. All rights reserved. You are allowed to copy it to BBS, Aminet and other free shareware-pools unless all files in this package are provided and unchanged. The use of gtdrag is at your own risk - I am not liable or responsible for any problems you might have. @endnode @node author "gtdrag - The Author" You can reach me under the following address: @{b}Snail-mail:@{ub} Axel Dörfler Heerstraße 53 49492 Westerkappeln Germany @{b}e-Mail:@{ub} axeld@ax.westfalen.de @{b}fidonet:@{ub} 2:2449/413.23@fidonet If you find a bug or have an idea to implement in gtdrag or if you want to become a beta tester of this library, please write me! @{u} @{uu} The gtdrag.library is compiled using the SAS/C-Compiler 6.51 on an A4000/040 with OS3.0 (V39). @{u} @{uu} @endnode @node credits "gtdrag - Credits" @{b}Thanks to:@{ub} - Daniel Rost (d96rost@ios.chalmers.se) for the creation of the E-modules and include files for gtdrag and the translation of the example program. @endnode @node intro "gtdrag - Introduction" The gtdrag shared library provides the possibility of the drag&drop-feature for gadtools-applications. It is thought to close the gap between now and an upcoming version of AmigaOS with this features included. If it comes. It is definitely not the best you can imagine, but it works good and is easy to use. You drag an entry of listview when you select it and move the mouse horizontal more than 10 pixels. On other gadget types, you have to move >3 pixels to start dragging. Perhaps I'll implement a special "dragkey" like "alt" or whatsoever. The drag&drop feature is not limited to a single window or application, every gadget you add, is included. But of course, it is limited to one screen at the same time. With the version 1.5 gtdrag is implemented in a shared library. This gives several advantages against the old linker library; if someone needs a linker library, I can create one on request. @endnode @node required "gtdrag - System requirements" gtdrag should work on any Amiga with OS 3.0+ (V39 and above). It is not possible to use it under OS 2.04. But you can also build an application which runs under 2.04 and an installed gtdrag.library - in this case gtdrag works as a gate to gadtools without the dragging capabilities. @endnode @node funcs "gtdrag - Function Overview" @{b}TABLE OF CONTENTS@{ub} @{"gtdrag.lib/GTD_AddApp" link GTD_AddApp} @{"gtdrag.lib/GTD_AddGadget" link GTD_AddGadget} @{"gtdrag.lib/GTD_AddWindow" link GTD_AddWindow} @{"gtdrag.lib/GTD_GetDragMsg" link GTD_GetDragMsg} @{"gtdrag.lib/GTD_FilterIMsg" link GTD_FilterIMsg} @{"gtdrag.lib/GTD_GetIMsg" link GTD_GetIMsg} @{"gtdrag.lib/GTD_PostFilterIMsg" link GTD_PostFilterIMsg} @{"gtdrag.lib/GTD_RemoveApp" link GTD_RemoveApp} @{"gtdrag.lib/GTD_RemoveGadget" link GTD_RemoveGadget} @{"gtdrag.lib/GTD_RemoveWindow" link GTD_RemoveWindow} @{"gtdrag.lib/GTD_ReplyDragMsg" link GTD_ReplyDragMsg} @{"gtdrag.lib/GTD_ReplyIMsg" link GTD_ReplyIMsg} @endnode @node GTD_AddApp "gtdrag.lib/GTD_AddApp" @{b}NAME@{ub} GTD_AddApp -- inits all app. dragging context data @{b}SYNOPSIS@{ub} result = GTD_AddApp(name,firsttag,...); D0 A0 A1 int GTD_AddApp(STRPTR,Tag,...); @{b}FUNCTION@{ub} This function allocates and sets all needed data. You must call it before any other action with this library. Every name must be unique. @{b}TAGS@{ub} GTDA_InternalOnly (BOOL) - if you don't want to react on dropped icons of other applications, you should set this flag to TRUE. Defaults to FALSE. @{b}RESULT@{ub} result - TRUE for success. @{b}SEE ALSO@{ub} @{"GTD_RemoveApp()" link GTD_RemoveApp}, @{"GTD_GetIMsg()" link GTD_GetIMsg} @endnode @node GTD_AddGadget "gtdrag.lib/GTD_AddGadget" @{b}NAME@{ub} GTD_AddGadget -- adds a drag&drop gadget to the internal list @{b}SYNOPSIS@{ub} GTD_AddGadget(type,gad,win,firsttag,...); D0 A0 A1 A2 void GTD_AddGadget(int,struct Gadget *,struct Window *,Tag,...); @{b}FUNCTION@{ub} This function adds the chosen gadget to the internal list. You must call this function, if you want a gadget to have the drag&drop-feature. @{b}TAGS@{ub} GTDA_Images (BOOL) - if specified, only the image of an ImageNode will be dragged. GTDA_Width & GTDA_Height MUST be set. Defaults to FALSE. GTDA_NoDrag (BOOL) - if specified, you cannot drag an item of this gadget; you are only able to drop them over it. Defaults to FALSE. GTDA_Same (BOOL) - for listviews. If specified, source and target of a drag can be the same. Defaults to FALSE. GTDA_NoPosition (BOOL) - for listviews only. If specified, there is no position highlightning or scrolling. Defaults to FALSE. GTDA_ItemHeight (short) - specifies the height of a listview entry. Defaults to the screen's font height. GTDA_RenderHook (struct Hook *) - if provided, the dragged image will be drawn with this listview-callback hook. Otherwise there is only a ClipBlit() proceeded, which will not work in combination with simple refresh windows. You can set a special size with GTDA_Width & GTDA_Height. Defaults to NULL. GTDA_Object (struct *ImageNode) - for non-listview gadgets: the node that will be dragged. If a render hook is provided, the object must be of a type accepted by the render hook. GTDA_Mask (ULONG) - the mask value for the gadget. Defaults to 0xffffffff. GTDA_AcceptMask (ULONG) - if the mask value of the dropped icon and (bit-wise) this value are TRUE, the drag will be accepted. Defaults to 0xffffffff. GTDA_Width, GTDA_Height (short) - set the size of the image to be dragged. @{b}INPUTS@{ub} type - type of the gadget (e.g. LISTVIEW_KIND) gad - pointer to the gadget (from CreateGadget()). win - pointer to the window of the gadget @{b}NOTES@{ub} If the gadget type is not LISTVIEW_KIND, GTDA_Object and GTDA_Images or GTDA_RenderHook must be set, or DGF_NODRAG will be set. Furthermore, you have to set the GA_Immediate-attribute to TRUE if want to have a draggable gadget. The function should only be used with GTDA_NoDrag when using other gadget types than LISTVIEW_KIND or BUTTON_KIND. Otherwise it could make problems (check it out). You MUST set the GadgetID field of your gadgets! @{b}SEE ALSO@{ub} @{"GTD_RemoveGadget()" link GTD_RemoveGadget}, @{"GTD_RemoveApp()" link GTD_RemoveApp} @endnode @node GTD_AddWindow "gtdrag.lib/GTD_AddWindow" @{b}NAME@{ub} GTD_AddWindow -- adds drag&drop notify to a window @{b}SYNOPSIS@{ub} GTD_AddWindow(win,firsttag,...); void GTD_AddWindow(struct Window *,Tag,...); @{b}FUNCTION@{ub} This function adds the chosen window to the internal list. You must call this function, if you want to receive drag& drop messages from a window. @{b}TAGS@{ub} GTDA_AcceptMask (ULONG) - if the mask value of the dropped icon and (bit-wise) this value are TRUE, the drag will be accepted. Defaults to 0xffffffff. @{b}INPUTS@{ub} win - pointer to the window @{b}NOTE@{ub} You only receive a DMT_WINDOW message from @{"GTD_GetDragMsg()" link GTD_GetDragMsg} if the object wasn't dropped over a gadget which supports drag&drop. @{b}SEE ALSO@{ub} @{"GTD_RemoveWindow()" link GTD_RemoveWindow}, @{"GTD_RemoveApp()" link GTD_RemoveApp} @endnode @node GTD_GetDragMsg "gtdrag.lib/GTD_GetDragMsg" @{b}NAME@{ub} GTD_GetDragMsg -- get a DragMsg if possible @{b}SYNOPSIS@{ub} dm = GTD_GetDragMsg(); struct DrawMsg *GTD_GetDragMsg(void); @{b}FUNCTION@{ub} If there are drag messages in the queue, this function returns the first one. @{b}RESULT@{ub} dm - a pointer to the message (NULL for none) @{b}NOTE@{ub} The dm_SourceApp field of the returned DragMsg is NULL if the dm_Source is one of the application's DragGadgets. @{b}SEE ALSO@{ub} @{"GTD_ReplyDragMsg()" link GTD_ReplyDragMsg} @endnode @node GTD_FilterIMsg "gtdrag.lib/GTD_FilterIMsg" @{b}NAME@{ub} GTD_FilterIMsg -- filter an IntuiMessage through gtdrag & gadtools. @{b}SYNOPSIS@{ub} modmsg = GTD_FilterIMsg(imsg); D0 A0 struct IntuiMessage *GTD_FilterIMsg(imsg); @{b}FUNCTION@{ub} see gadtools/GT_FilterIMsg(). @{b}INPUT@{ub} imsg - an IntuiMessage you got from GetMsg(). @{b}RESULT@{ub} modmsg - pointer to the modified IntuiMessage @{b}SEE ALSO@{ub} @{"GTD_PostFilterIMsg()" link GTD_PostFilterIMsg} @endnode @node GTD_GetIMsg "gtdrag.lib/GTD_GetIMsg" @{b}NAME@{ub} GTD_GetIMsg -- get an IntuiMessage, with all necessary processing @{b}SYNOPSIS@{ub} msg = GTD_GetIMsg(port); struct IntuiMessage *GTD_GetIMsg(iport); @{b}FUNCTION@{ub} Gets an IntuiMessage and does all the drag processing including a call to the aquivalent gadtools functions. @{b}INPUT@{ub} port - a pointer to the msg port @{b}RESULT@{ub} msg - pointer to the IntuiMessage @{b}SEE ALSO@{ub} @{"GTD_ReplyIMsg()" link GTD_ReplyIMsg} @endnode @node GTD_PostFilterIMsg "gtdrag.lib/GTD_PostFilterIMsg" @{b}NAME@{ub} GTD_PostFilterIMsg -- return filtered IntuiMessage from GTD_FilterIMsg(). @{b}SYNOPSIS@{ub} msg = GTD_PostFilterIMsg(modimsg); D0 A0 struct IntuiMessage *GTD_FilterIMsg(imsg); @{b}FUNCTION@{ub} see gadtools/GT_FilterIMsg(). @{b}INPUT@{ub} modimsg - an IntuiMessage you got from GTD_FilterIMsg(). @{b}RESULT@{ub} msg - pointer to the unmodified IntuiMessage @{b}SEE ALSO@{ub} @{"GTD_FilterIMsg()" link GTD_FilterIMsg} @endnode @node GTD_RemoveApp "gtdrag.lib/GTD_RemoveApp" @{b}NAME@{ub} GTD_RemoveApp -- frees the dragging context data @{b}SYNOPSIS@{ub} GTD_RemoveApp(); void GTD_RemoveApp(void); @{b}FUNCTION@{ub} Frees all the memory allocated by GTD_AddApp(), GTD_AddGadget() and GTD_AddWindow() for an application. You should not call it without the GTD_AddApp() call before. @{b}SEE ALSO@{ub} @{"GTD_AddApp()" link GTD_AddApp}, @{"GTD_AddGadget()" link GTD_AddGadget}, @{"GTD_AddWindow()" link GTD_AddWindow} @endnode @node GTD_RemoveGadget "gtdrag.lib/GTD_RemoveGadget" @{b}NAME@{ub} GTD_RemoveGadget -- removes a drag&drop gadget @{b}SYNOPSIS@{ub} GTD_RemoveGadget(gad); void GTD_AddGadget(struct Gadget *); @{b}FUNCTION@{ub} This function removes the drag&drop feature from a gadget which was added to it with GTD_AddGadget(). @{b}INPUTS@{ub} gad - pointer to the gadget (from CreateGadget()). @{b}SEE ALSO@{ub} @{"GTD_AddGadget()" link GTD_AddGadget}, @{"GTD_RemoveApp()" link GTD_RemoveApp} @endnode @node GTD_RemoveWindow "gtdrag.lib/GTD_RemoveWindow" @{b}NAME@{ub} GTD_RemoveWindow -- removes drag&drop notify from a window @{b}SYNOPSIS@{ub} GTD_RemoveWindow(win); void GTD_RemoveWindow(struct Window *); @{b}FUNCTION@{ub} Removes drag&drop notfiy from a window which was added with GTD_AddWindow() before. @{b}INPUTS@{ub} win - pointer to the window @{b}SEE ALSO@{ub} @{"GTD_AddWindow()" link GTD_AddWindow}, @{"GTD_RemoveApp()" link GTD_RemoveApp} @endnode @node GTD_ReplyDragMsg "gtdrag.lib/GTD_ReplyDragMsg" @{b}NAME@{ub} GTD_ReplyDragMsg -- replies a DragMsg @{b}SYNOPSIS@{ub} GTD_ReplyDragMsg(dm); void GTD_ReplyDragMsg(struct DragMsg *); @{b}FUNCTION@{ub} Replies a drag msg got from GTD_GetDragMsg(). @{b}INPUT@{ub} dm - a pointer to the drag msg @{b}SEE ALSO@{ub} @{"GTD_GetDragMsg()" link GTD_GetDragMsg} @endnode @node GTD_ReplyIMsg "gtdrag.lib/GTD_ReplyIMsg" @{b}NAME@{ub} GTD_ReplyIMsg -- replies an IntuiMessage @{b}SYNOPSIS@{ub} GTD_ReplyIMsg(msg); void GTD_ReplyIMsg(struct IntuiMessage *); @{b}FUNCTION@{ub} Replies the msg got from GTD_GetIMsg(). It works like GT_ReplyIMsg() - but you must call GTD_GetIMsg() before! @{b}INPUT@{ub} msg - a pointer to the msg to be replied, maybe NULL. @{b}SEE ALSO@{ub} @{"GTD_GetIMsg()" link GTD_GetIMsg} @endnode @node release "gtdrag - Release Notes" gtdrag 1.1 (29.9.96) - first release. gtdrag 1.4 (3.10.96) - big changes in structure and tag definitions! (1.2) - other gadget types than LISTVIEW_KIND will be handled correctly (like BUTTON_KIND). (1.2) - added @{"GTD_RemoveGadget()" link GTD_RemoveGadget} and @{"GTD_RemoveWindow()" link GTD_RemoveWindow} for multi-window support. (1.2) - checks now for the number of entries in a source-listview. (1.3) - the range of a mouse move until a drag happens can now be changed via GTDA_(LV)DragPixel. (1.3) - the dragged icon now hides if you are near the source gadget to prevend graphical damage. (1.4) --------- gtdrag 1.8 (5.11.96) - created a shared library, the linker lib is not provided anymore but I can create one on request. This creation is part of big changes in the whole application interface. E. g. the GTD_Init()/ Free() function-pair doesn't exist any longer. (1.5) - implemented GTD_(Post)FilterIMsg()-functions. (1.6) - checks now the number of entries in the target-listview. (1.6) - makes the dragged object transparent if it is over a gadget which accepts drag&drop. (1.6) - now centers the dragged object if it is an image. (1.7) - fixed problems with more than one window open at a time. (1.8) - fixed the GTD_(Post)FilterIMsg()-functions; they replied the same IntuiMessage two times. (1.8) gtdrag 2.1 (7.11.96) - implemented accept and type masks. (1.9) - implemented GTDA_InternalOnly and GTDA_Same. (1.9) - changed the handling of the DragMsgs internally. (1.10) - bumped to V2 to let applications presuppose the extensions to the last release. (2.1) - it was possible to get a drag message (DMT_UNKNOWN) if a drag was interrupted using the right mouse button. (2.1) gtdrag 2.2 (11.11.96) - if no DragGadget was defined, this could make problems. (2.2) - fixed possible problems with the use of Wait() in applications. (2.2) - the GTDA_RenderHook got one pixel too much in width and height. (2.2) gtdrag 2.7 (15.12.96) - the drag objects are now rendered via BitMaps, they are no BOBs any longer to reduce flickering on gfx-cards. (2.3) - include the E includes/modules made by Daniel Rost. (2.3) - fixed small bugs in the render-routine. (2.3) - a little more highlightning is done. (2.4) - the render-routines were a bit optimised and changed for use with CyberGraphX. (2.5) - the message handling is completely changed, now it uses fake events to let gadtools stop processing messages while an object is dragged. (2.6) - small optimisations. (2.6) - enhanced highlightning and listview-control. If you move an entry in a listview, you may get another dm_TargetEntry than in previous releases. (2.6) - added scrolling capabilities to listview-drags. (2.6) - some minor bug fixes. (2.7) @endnode @node bugs "gtdrag - Known Bugs" Unfortunately, there are bugs left: - on CyberGraphX-screens with more than 256 colors the drag object is not rendered correctly. - it is much too slow on a graphic-card; I know the reason for that but I don't know how to fix it. @endnode @node todo "gtdrag - To do list" There are a few things on the "to do"-list: - better CyberGraphX support (see @{"known bugs" link bugs}) - standards for "interprocess" drag&drop That's not all, but I obviously forgot the rest. @endnode