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.