/*
    ####             #    #     # #
    #   #            #    #       #          The FreeWare C library for 
    #   #  ##   ###  #  # #     # ###             RISC OS machines
    #   # #  # #     # #  #     # #  #   ___________________________________
    #   # ####  ###  ##   #     # #  #                                      
    #   # #        # # #  #     # #  #    Please refer to the accompanying
    ####   ### ####  #  # ##### # ###    documentation for conditions of use
    ________________________________________________________________________

    File:    Drag.h
    Author:  Copyright  1994 Jason Williams
    Version: 1.00 (01 April 1994)
    Purpose: Automatic handling of drag update and finish events
*/

#ifndef __dl_drag_h
#define __dl_drag_h

#ifdef __cplusplus
extern "C" {
#endif


#ifndef __dl_core_h
#include "Core.h"
#endif


extern void Drag_Initialise(BOOL attachNULLhandler);
/*
This function initialises the drag system for use with the Event
sublibrary, registering Handler_DragNULL and Handler_DragFinish with
Event.

If you don't use Event, you'll need to do something along similar lines
for yourself.

attachNULLhandler should be TRUE if you want to use an update handler
(for e.g. redrawing a selection as the user drags), or FALSE if you do
not want an update handler ever (if, e.g. the only drags you use are for
file saves etc where the WIMP/DragASpr takes care of all redrawing)

(See below for a description of how dragging should be done)
*/


/*  Drag handlers ------------------------------------------------------------
 *  During a drag, the currentupdate proc is called on each NULL event
 *  When a drag operation completes, currentcomplete proc is called.
 *  The userdata is passed in to both of these functions to indicate
 *  just what drag is being updated.
 *  (See below)
 */

typedef void (* drag_handler) (void *userdata);

extern drag_handler drag_currentupdate;
extern drag_handler drag_currentcomplete;
extern void         *drag_currentuserdata;


extern void Drag_SetHandlers(drag_handler uproc, drag_handler cproc,
                             void *userdata);
/*
When you wish to do a drag operation, do the following:

* Call Wimp_DragBox (or equivalent) as appropriate to start the WIMP 
  dragging.

* Call Drag_SetHandlers to set the procedures that will be called on
  each NULL event during dragging, and on completion of the drag
  operation.

* Sit back, and let the event handlers do all (well, some of) the work.

Your handler(s) may be NULL, in which case that handler is not called.

'userdata' is anything you wish, and is passed into your handlers for
convenience.

Your handlers should each be a drag_handler.

eg.

void MyDragUpdateHandler(void *myuserdata)
{
(e.g. Get Mouse info and redraw selection)
}

void MyDragFinishHandler(void *myuserdata)
{
(e.g. Set new selection,
or save a file if dragging an icon, etc)
}
*/


#ifdef __cplusplus
}
#endif


#endif
