RISC OS  OPEN

DRAGANOBJECT MODULE API SPECIFICATION
=====================================

Description
-----------

   DragAnObject is very similar to DragASprite in that it allows a graphic
to be dragged around the screen in place of the pointer. It differs by 
allowing an arbitrary graphic as opposed to just a sprite to be dragged.
This is achieved by calling a renderer. The current implementation calls
this renderer twice so that a (possibly irregular) mask can be built on the
fly. This makes it possible to drag icons (using Wimp_PlotSprite as a 
renderer), toolbox gadgets, or even draw objects.    

SWIs
----

 DragAnObject_Start
 ------------------

  Entry as DragASprite_Start, except

  R0 flags:
    bit 16 if set then R1 is a function pointer else a SWI number
    bit 17 if set then if R1 is a function it will be called in SVC mode
           (ie. to be used for modules - allows access to statics as well)
    all other flags as DragASprite_Start

  R1 
    function pointer or SWI number for renderer

  R2 
    parameters to function or packed registers to SWI

  Usage:

    As DragASprite_Start, this SWI starts the dragging process (calling
DragASprite_Start and in turn Wimp_DragBox on the clients behalf), usually
in response to a Drag (Button Click) Event.

    The renderer can be a C (or assembler) function or a SWI (determined 
by setting bits 16 and 17 in the flags word) Eg.

SWI renderer:

void start_drag(...)
{
   _kernel_swi_regs regs, render;

   render.r[1] = (int) &icon;

   /* oh dear, bug in the wimp */

   render.r[4] =0;
   render.r[5] =0;

   regs.r[0] = some flags;
   regs.r[1] = Wimp_PlotIcon;
   regs.r[2] = (int) &render;
   regs.r[3] = (int) &bbox;

   _kernel_swi(DragAnObject_Start,&regs,&regs);
}

Code renderer:

void _my_render(data)
{
   /* do the render */

}                   

void start_drag(...)
{
   _kernel_swi_regs regs;
   int render[4];

   /* render[0] ... render[3] will be passed to the function as parameters */

   render[0] = (int) data required by renderer;

   /* tell it we're a function and a module */

   regs.r[0] = some flags + (1<<16) + (1<<17);
   regs.r[1] = (int) _my_render;
   regs.r[2] = (int) &render;
   regs.r[3] = (int) &bbox;

   _kernel_swi(DragAnObject_Start,&regs,&regs);
}

 DragAnObjectStop
 ----------------

  Usage:

    Stops dragging - current implementation just calls DragASprite_Stop.