(*
 * Title:  coords.h
 * Purpose:  Provide common coordinate conversion functions
 *
 *)

(*
 * This file contains functions for working in the window coordinate
 * system. Functions are provided to convert between screen and work area
 * coordinates, and perform other simple operations on points, lines, 
 * "boxes".
 * It is conventional to think of the point (0,0) as appearing at the top
 * left-hand corner of a document.
 *
 *)

#ifndef __coords_h
#define __coords_h

#ifndef __wimp_h
#include "wimp.h"
#endif


(* Type used for box and scroll position *)

type coords_cvtstr_ptr = ^coords_cvtstr;
     coords_cvtstr =
       record
         box : wimp_box;
         scx, scy : integer
       end;

(* Type for points *)
type coords_pointstr_ptr = ^coords_pointstr;
     coords_pointstr =
       record
         x, y : integer
       end;



(* ------------------ coords_x_toscreen/coords_y_toscreen ------------------
 * Description:   Convert x/y work area coordinates into x/y screen
 *                coordinates.
 *
 * Parameters:    int x or int y -- x or y coordinate in work area coords
 *                coords_cvtstr *r -- conversion box (screen coords and
 *                                                    scroll offsets).
 * Returns:       x or y screen coordinates.
 * Other Info:    none.
 *
 *)
function coords_x_toscreen(x : integer;
                r : coords_cvtstr_ptr) : integer; extern;
function coords_y_toscreen(y : integer;
                r : coords_cvtstr_ptr) : integer; extern;


(* ----------------- coords_x_toworkarea/coords_y_toworkarea ---------------
 * Description:   Convert x/y screen coordinates into x/y work area
 *                coordinates.
 *
 * Parameters:    int x or int y -- x or y coordinate in screen coords
 *                coords_cvtstr *r -- conversion box (screen coords and
 *                                                    scroll offsets).
 * Returns:       x or y work area coordinates.
 * Other Info:    none.
 *
 *)
function coords_x_toworkarea(x : integer;
                r : coords_cvtstr_ptr) : integer; extern;
function coords_y_toworkarea(y : integer;
                r : coords_cvtstr_ptr) : integer; extern;


(* ------------------------ coords_box_toscreen ----------------------------
 * Description:   Converts a "box" of workarea coordinates into a "box" of
 *                screen coordinates.
 *
 * Parameters:    wimp_box *b -- workarea box to be converted
 *                coords_cvtstr *r -- conversion box (screen coords and
 *                                                    scroll offsets).
 * Returns:       void.
 * Other Info:    "b" is converted "in situ" into screen coordinates (ie. 
 *                its contents change).
 *
 *)
procedure coords_box_toscreen(b : wimp_box_ptr;
                r : coords_cvtstr_ptr); extern;


(* ------------------------ coords_box_toworkarea --------------------------
 * Description:   Converts a "box" of screen coordinates into a "box" of
 *                workarea coordinates.
 *
 * Parameters:    wimp_box *b -- screen box to be converted
 *                coords_cvtstr *r -- conversion box (screen coords and
 *                                                    scroll offsets).
 * Returns:       void.
 * Other Info:    "b" is converted "in situ" into workarea coordinates (ie.
 *                its contents are changed).
 *
 *)
procedure coords_box_toworkarea(b : wimp_box_ptr;
                r : coords_cvtstr_ptr); extern;


(* ------------------------- coords_point_toscreen -------------------------
 * Description:   Converts a point (x,y) from workarea coordinates to screen
 *                coordinates.
 *
 * Parameters:    coords_pointstr *point -- the point in workarea coordinates
 *                coords_cvtstr *r -- conversion box (screen coords and
 *                                                    scroll offsets).
 * Returns:       void.
 * Other Info:    "point" is converted "in situ" into screen coordinates
 *                (ie. its contents are changed).
 *
 *)
procedure coords_point_toscreen(point : coords_pointstr_ptr;
                r : coords_cvtstr_ptr); extern;


(* ------------------------- coords_point_toworkarea -----------------------
 * Description:   Converts a point (x,y) from screen coordinates to workarea
 *                coordinates.
 *
 * Parameters:    coords_pointstr *point -- the point in screen coordinates
 *                coords_cvtstr *r -- conversion box (screen coords and
 *                                                    scroll offsets).
 * Returns:       void.
 * Other Info:    "point" is converted "in situ" into workarea coordinates
 *                (ie. its contents are changed).
 *
 *)
procedure coords_point_toworkarea(point : coords_pointstr_ptr;
                r : coords_cvtstr_ptr); extern;


(* -------------------------- coords_withinbox -----------------------------
 * Description:   Informs caller if a point (x,y) lies within a "box".
 *
 * Parameters:    coords_pointstr *point -- the point
 *                wimp_box *box -- the box.
 * Returns:       TRUE if point lies within the box.
 * Other Info:    none.
 *
 *)
function coords_withinbox(point : coords_pointstr_ptr;
                box : wimp_box_ptr) : boolean; extern;


(* ------------------------- coords_offsetbox ------------------------------
 * Description:   Offset a "box" by a given "x" and "y" displacement.
 *
 * Parameters:    wimp_box *source -- the box to be moved
 *                int byx -- "x" displacement
 *                int byy -- "y" displacement
 *                wimp_box *result -- box when offset.
 * Returns:       void.
 * Other Info:    "source" and "result" are permitted to point at the same
 *                box.
 *
 *)
procedure coords_offsetbox(source : wimp_box_ptr;
                byx, byy : integer;
                result : wimp_box_ptr); extern;


(* ------------------------- coords_intersects -----------------------------
 * Description:   Informs caller whether a line intersects a given "box"
 *
 * Parameters:    wimp_box *line -- the line
 *                wimp_box *rect -- the box
 *                int widen -- width of line (same units as line and rect).
 * Returns:       TRUE if line intersects box.
 * Other Info:    none.
 *
 *)
function coords_intersects(line : wimp_box_ptr;
                rect : wimp_box_ptr;
                widen : integer) : boolean; extern;


(* ------------------------- coords_boxesoverlap ---------------------------
 * Description:   Informs caller whether two "boxes" cover any common area.
 *
 * Parameters:    wimp_box *box1 -- one box
 *                wimp_box *box2 -- the other box.
 * Returns:       TRUE if boxes overlap.
 * Other Info:    none.
 *
 *)
function coords_boxesoverlap(box1, box2 : wimp_box_ptr) : boolean; extern;

#endif

(* end coords.h *)
