home *** CD-ROM | disk | FTP | other *** search
/ Amiga Times / AmigaTimes.iso / demos / programme / Wildfire_PPC / Bonus / draggadget_r1.0b2 / Doc / drag_gc.doc < prev   
Encoding:
Text File  |  1998-10-06  |  11.7 KB  |  311 lines
  1. TABLE OF CONTENTS
  2.  
  3. drag.gadget/--drag.gadget--
  4. drag.gadget/AddDropWindow
  5. drag.gadget/CreateDContext
  6. drag.gadget/DeleteDContext
  7. drag.gadget/FreeDragGroup
  8. drag.gadget/NewDragGroup
  9. drag.gadget/OM_DROPACTION
  10. drag.gadget/RemoveDropWindow
  11. drag.gadget/--drag.gadget--                       drag.gadget/--drag.gadget--
  12.  
  13.    NAME
  14.        drag.gadget -- gadget class for drag & drop actions.
  15.  
  16.    FUNCTION
  17.        The drag gadget class provides simple access to drag and drop
  18.        functionality. It supports notifying of target objects, dragging of
  19.        gadget groups, animated images and relativity flags (GA_RelBottom and
  20.        GA_RelRight).
  21.        The IClass* can be obtained from the cl_Class field of the
  22.        ClassLibrary structure.
  23.        AmigaOS3.0 (V39) is required.
  24.  
  25.    METHODS
  26.        GM_RENDER - the gadget image is drawn according to the state of
  27.             GFLG_SELECTED and GFLG_GADGHIGHBITS. The images may be provided
  28.             with the GA_Image and GA_SelectRender tags, at least GA_Image
  29.             must be provided. If the DGA_DragImage or DGA_DragAnim tags are
  30.             not used, the SelectRender or normal image are also used for the
  31.             drag gadget's bob. In this case the supplied image may not be a
  32.             BOOPSI object.
  33.  
  34.        OM_DROPACTION - this method is called if another drag gadget is
  35.             dropped on this gadget. For the drag gadget class, it invokes a
  36.             hook function if one is supplied via DGA_DropActHook. It may be
  37.             implemented for other gadget classes if they are used as drop
  38.             targets.
  39.  
  40.        GM_GOACTIVE - the gadget changes its state to selected and activates
  41.             its bob. If the gadget belongs to a drag group, all other members
  42.             are deselected. If SHIFT was pressed, instead the bobs of all
  43.             selected members are activated, too.
  44.  
  45.        GM_HANDLEINPUT - If the mouse is moved, all activated bobs are moved
  46.             accordingly. If the right mouse button is pressed (cancel), all
  47.             bobs are deactivated and the related gadgets deselected.
  48.  
  49.        GM_GOINACTIVE - If the action was not cancelled, its target is
  50.             identified: if the mouse pointer is in a "known" window (see
  51.             AddDropWindow()), that window is the target. If the pointer is
  52.             placed over a BOOPSI gadget within such a window, the gadget is
  53.             the target. Otherwise no target is found, only the pointer
  54.             position is noted. The target position, type and object can be
  55.             found in the DragInfo structure (see DGA_DragInfo). If the target
  56.             is a DropWindow, a message is send to the related port. If the
  57.             target is a BOOPSI gadget, the BOOPSI message OM_DROPACTION is
  58.             send to that gadget.
  59.  
  60.    ATTRIBUTES
  61.        DGA_ExtSelect (I) - default value is FALSE. If this attribute is set,
  62.             the gadget stays selected after dropping. If it belongs to a
  63.             drag group and another gadget of that group is selected with
  64.             SHIFT pressed, this gadget's bob is also activated.
  65.  
  66.        DGA_Context (I) - context for the gadget's bob. See CreateDContext().
  67.  
  68.        DGA_Screen/DGA_Window (I) - screen/window of the gadget's bob. These
  69.             attributes and DGA_Context are mutually exclusive. With these
  70.             attributes, no locking is provided, so it may only be used, if
  71.             the application has exclusive access to the supplied
  72.             window/screen. Additionally, the first gadget created with one
  73.             of these tags must be disposed as the last one. In general, it is
  74.             better to use DGA_Context.
  75.  
  76.        DGA_DragInfo (G) - after a drop action, the application finds details
  77.             in the DragInfo structure, which is found using this tag.
  78.  
  79.        DGA_DragImage (IS) - if this attribute is set, the bob's imagery is
  80.             not taken from GA_Image or GA_SelectRender, but from the supplied
  81.             image. It may not be a BOOPSI object, i.e. its ImageData pointer
  82.             must be initialised.
  83.  
  84.        DGA_DragAnim (IS) - with this tag a NULL-terminated array of image
  85.             pointers can be supplied. They will be used as animated bob
  86.             imagery. None of them may be a BOOPSI object.
  87.  
  88.        DGA_AnimSpeed (IS) - this tag controls the speed of the bob animation
  89.             in ticks/second. There are approximately ten ticks per second, so
  90.             a value of 1 (default) will result in ten pictures per second.
  91.             A value of 0 causes the animation to stop, i.e. the current image
  92.             will never be changed.
  93.  
  94.        DGA_DragGroup (IS) - Setting this attribute adds the gadget to a drag
  95.             group (see NewDragGroup()). A value of NULL removes the gadget
  96.             from its group. All member gadgets of a group should be within
  97.             the same window/requester/domain.
  98.  
  99.        DGA_DropActHook (I) - this hook is called from the OM_DROPACTION
  100.             method, if another drag gadget is dropped on this gadget.
  101.             The hook function gets a pointer to this gadget in register A2
  102.             (Object) and a pointer to the DragInfo structure of the dropped
  103.             gadget in A1 (Message). Note that this hook function is executed
  104.             in context of input.device, which is a task, not a process. That
  105.             means no DOS functions may be called!
  106.  
  107.    NOTES
  108.        The driver software of some graphics cards seems to introduce a bug
  109.        with the GELS animation system, causing the system to crash if
  110.        animated bobs are used. If this is the case for your system, it can be
  111.        resolved with the patchgels program (see patchgels drawer).
  112.  
  113. drag.gadget/AddDropWindow                           drag.gadget/AddDropWindow
  114.  
  115.    NAME
  116.        AddDropWindow -- add a window to the dropwindow list of a drag
  117.                         context.
  118.  
  119.    SYNOPSIS
  120.        dropwindow = AddDropWindow(context, id, userdata, window, msgport);
  121.        D0                         A2       D0  D1        A0      A1
  122.  
  123.        APTR AddDropWindow(APTR, ULONG, ULONG, struct Window *,
  124.                           struct MsgPort *);
  125.  
  126.    FUNCTION
  127.        Add the window to the context's list of dropwindows. All drag gadgets
  128.        using the context now "know" this window; it may be target of drop
  129.        actions. If the drag gadgets are using no context but the DGA_Window
  130.        tag, that single window is automatically the only known window.
  131.        If a message port is supplied, the application is notified if drag
  132.        gadgets are dropped inside that window (not hitting any gadgets).
  133.        The notification consists of a DropMessage (see drag.h) of type
  134.        DMTYPE_DROPWINDOW.
  135.  
  136.    INPUTS
  137.        context - a context pointer (see CreateDContext()). The window is to
  138.                  be included into it's dropwindow list.
  139.        id - with this variable you you can give the dropwindow an id to
  140.             identify it in the dropmessage.
  141.        userdata - this variable is for your own use.
  142.        window - pointer to window to add.
  143.        msgport - pointer to a message port or NULL.
  144.  
  145.    RESULT
  146.        dropwindow - pointer to a dropwindow structure. This is passed to
  147.                     RemoveDropWindow to remove the window from the list of
  148.                     dropwindows. NULL for failure.
  149.  
  150.    NOTES
  151.  
  152.    SEE ALSO
  153.        RemoveDropWindow() ,CreateDContext(), DeleteDContext(),
  154.        <drag.h>
  155.  
  156. drag.gadget/CreateDContext                         drag.gadget/CreateDContext
  157.  
  158.    NAME
  159.        CreateDContext -- create a context for drag gadgets.
  160.  
  161.    SYNOPSIS
  162.        context = CreateDContext(screen);
  163.         D0                       A0
  164.  
  165.        APTR CreateDContext(struct Screen *);
  166.  
  167.    FUNCTION
  168.        A context is created for drag gadgets used on a public (shared)
  169.        screen. This includes a copy of the screen's rastport initialised
  170.        with an own GelsInfo structure. The returned value may be used with
  171.        the DGA_Context tag. The resulting bobs can be moved on the specified
  172.        screen. If the bobs should be moveable only within a certain window,
  173.        use the DGA_Window tag instead, which doesn't need a context.
  174.  
  175.    INPUTS
  176.        screen - Screen the bobs should appear on. The window the drag gadgets
  177.                 are placed in should be on the same screen.
  178.  
  179.    RESULT
  180.        context - pointer to be passed to drag gadgets via DGA_Context. NULL
  181.                  if failure.
  182.  
  183.    NOTES
  184.  
  185.    SEE ALSO
  186.        DeleteDContext(), AddDropWindow(), RemoveDropWindow()
  187.  
  188. drag.gadget/DeleteDContext                         drag.gadget/DeleteDContext
  189.  
  190.    NAME
  191.        DeleteDContext -- delete a drag context.
  192.  
  193.    SYNOPSIS
  194.        DeleteDContext(context);
  195.                        A0
  196.  
  197.        VOID DeleteDContext(APTR);
  198.  
  199.    FUNCTION
  200.        Frees any memory and resources allocated by CreateDContext(). All drag
  201.        gadgets using the context must have been disposed. If any windows are
  202.        still in the dropwindow list, they are removed from the list first.
  203.  
  204.    INPUTS
  205.        context - Pointer obtained by CreateDContext() or NULL.
  206.  
  207.    NOTES
  208.  
  209.    SEE ALSO
  210.        CreateDContext(), AddDropWindow(), RemoveDropWindow()
  211.  
  212. drag.gadget/FreeDragGroup                           drag.gadget/FreeDragGroup
  213.  
  214.    NAME
  215.        FreeDragGroup -- dispose a draggroup structure.
  216.  
  217.    SYNOPSIS
  218.        FreeDragGroup(draggroup);
  219.                      A0
  220.  
  221.        VOID FreeDragGroup(APTR);
  222.  
  223.    FUNCTION
  224.        Remove a draggroup obtained by NewDragGroup(). All member gadgets of
  225.        this group should have been removed by setting their DGA_DragGroup
  226.        attribute to NULL.
  227.  
  228.    INPUTS
  229.        draggroup - pointer to a draggroup structure or NULL.
  230.  
  231.    NOTES
  232.  
  233.    SEE ALSO
  234.        NewDragGroup()
  235.  
  236. drag.gadget/NewDragGroup                             drag.gadget/NewDragGroup
  237.  
  238.    NAME
  239.        NewDragGroup -- create a context to handle groups of drag gadgets.
  240.  
  241.    SYNOPSIS
  242.        draggroup = NewDragGroup();
  243.        D0
  244.  
  245.        APTR NewDragGroup(VOID);
  246.  
  247.    FUNCTION
  248.        The draggroup context enables groups of drag gadgets to communicate
  249.        with each other. If a drag gadget is selected, it deselects the other
  250.        members of its group. If it is SHIFT-selected and dropped to a target,
  251.        all selected members are dropped together, with their DropInfo
  252.        structures linked. (See DGA_DragGroup)
  253.  
  254.    RESULT
  255.        draggroup - pointer to a draggroup structure which may be passed to
  256.                    drag gadgets via the DGA_DragGroup tag. NULL for failure.
  257.  
  258.    NOTES
  259.  
  260.    SEE ALSO
  261.        FreeDragGroup()
  262.  
  263. drag.gadget/OM_DROPACTION                           drag.gadget/OM_DROPACTION
  264.  
  265.    NAME
  266.        OM_DROPACTION -- react if a drag gadget is dropped on this gadget.
  267.  
  268.    FUNCTION
  269.        This method is invoked if a drag gadget is dropped on this gadget. For
  270.        the drag gadget class it calls a hook function if one is supplied via
  271.        DGA_DropActHook.
  272.        This method enables any gadget class to act as target for drop
  273.        actions. It "simply" has to be implemented for the desired class.
  274.        A common way of communicating to the target gadget is to supply
  275.        information in the UserData field of the drag gadget which is copied
  276.        into the DragInfo structure of this message.
  277.  
  278.    RESULT
  279.        TRUE if this method is implemented.
  280.  
  281.    NOTES
  282.  
  283.    SEE ALSO
  284.        <drag.h>
  285.  
  286. drag.gadget/RemoveDropWindow                     drag.gadget/RemoveDropWindow
  287.  
  288.    NAME
  289.        RemoveDropWindow -- remove a window from it's list of dropwindows.
  290.  
  291.    SYNOPSIS
  292.        RemoveDropWindow(dropwindow);
  293.                         A0
  294.  
  295.        VOID RemoveDropWindow(APTR);
  296.  
  297.    FUNCTION
  298.        Remove a dropwindow from the dropwindow list it has been added to.
  299.        If a message port has been attached to the dropwindow, you must make
  300.        sure that all dropmessages are replied after removing the window.
  301.  
  302.    INPUTS
  303.        dropwindow - pointer to a dropwindow structure returned by
  304.                     AddDropWindow() or NULL.
  305.  
  306.    NOTES
  307.  
  308.    SEE ALSO
  309.        AddDropWindow(), CreateDContext(), DeleteDContext()
  310.  
  311.