/* Copyright 1996 Acorn Computers Ltd
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/****************************************************************************
* This source file was written by Acorn Computers Limited. It is part of *
* the RISCOS library for rendering RISCOS Draw files from applications *
* in C. It may be used freely in the creation of programs for Archimedes. *
* It should be used with Acorn's C Compiler Release 3 or later. *
* *
***************************************************************************/
/*
* Title: drawfdiag.h
* Purpose: Processing of Draw format files (diagram level interface)
*
*/
/*
*
* This file defines the interface to the simplest version of the
* DrawFile module. It can read in files to diagrams and render them.
* There is no checking of whether we have overrun the end of the
* diagram.
*
* To read in Draw files, it is expected that the caller will do the
* work of the I/O themselves.
*
* To dispose of a diagram, the caller can just throw it away, ie,
* the module does not keep any hidden information about what
* diagrams it has seen.
*
* Note on returning errors: some calls return an offset to the bad data on
* an error. This is not necessarily the start of an object: it may be bad
* data part way through it. The offset is relative to the start of the
* diagram.
*
* The module cannot handle rectangle or ellipse objects. Use a path instead.
*/
#ifndef __drawfdiag_h
#define __drawfdiag_h
#ifndef __os_h
#include "os.h"
#endif
#ifndef BOOL
#define BOOL int
#define TRUE 1
#define FALSE 0
#endif
/********************************* Data types ******************************/
/*
* Type for a diagram: it consists of a pointer to the data and a
* length field. The length must be an exact number of words, and is
* the amount of space used in the diagram, not the size of the
* memory allocated to it.
*/
typedef struct
{ char * data;
int length;
} draw_diag;
/* --- Abstract handle for an object --- */
/* The object handle is an offset from the start of the diagram to the
* object data. You may use it to set a pointer directly to an object,
* when using the object level interface
*/
typedef int draw_object;
/* --- Rectangular box: bounding boxes, etc. --- */
typedef struct {int x0, y0, x1, y1;} draw_box;
/* --- Redraw structure: similar to a wimp_redrawstr --- */
typedef struct
{
int reserved;
draw_box box; /* Work area box (x0, y1 used) */
int scx, scy; /* Scroll positions */
draw_box g; /* Graphics window box */
} draw_redrawstr;
/* Error type.
* Where a routine can produce an error, the actual value returned is a BOOL,
* which is TRUE if the routine succeeded. The error itself is returned in a
* block passed by the user; if NULL, then the details of the error are not
* passed back.
* The error block may contain either an operating system error, or an
* internal error. In the latter case, it consists of a code and possibly a
* pointer to the location in the file where the error occurred (if NULL,
* the location is not known or not specified). By convention, this should
* be reported by the caller in the form '<message> (location &xx in file)'.
* For a list of codes and standard errors, see h.DrawErrors. The location is
* relative to the start of the data block in the diagram.
*
*/
typedef struct
{
enum { DrawOSError, DrawOwnError, None } type;
union
{
os_error os;
struct { int code; int location; } draw;
} err;
} draw_error;
/*----------------------------- Macros ---------------------------*/
/* Macros for unit conversion between Draw units and screen units */
#define draw_drawToScreen(i) ((i) >> 8)
#define draw_screenToDraw(i) ((i) << 8)
/****************************** Function declarations **********************/
/* ------------------------- draw_verify_diag ------------------------------
* Description: Verifies a diagram which has been read in from file
*
* Parameters: draw_diag *diag -- the diagram to be verified
* draw_error *error -- the first error encountered (if any)
* Returns: True if diagram is correct.
* Other Info: Each object in the file is checked and the first error
* encountered causes return (with error set appropriately)
*
*/
BOOL draw_verify_diag(draw_diag *diag, draw_error *error);
/* ------------------------- draw_append_diag ------------------------------
* Description: Merges two diagrams into one.
*
* Parameters: draw_diag *diag1 -- diagram to which to append diag2
* draw_diag *diag2 -- diagram to be appended to diag1
* draw_error *error -- possible error condition.
* Returns: True if merge was successful.
* Other Info: Both diagrams should have been processed by
* draw_verify_diag(). Diag1's data block must be at least
* diag1.length+diag2.length. Diag1.length will be updated
* to its new appropriate value. Diag1's bounding box will
* be set to the union of the bounding boxes of the two
* diagrams. NOTE: offsets of objects in diag1 may change
* due to a change in font table size (if diag2 has fonts).
* Errors referring to specific locations, refer to diag2.
*
*/
BOOL draw_append_diag(draw_diag *diag1, draw_diag *diag2, draw_error *error);
/* -------------------------- draw_render_diag -----------------------------
* Description: Render a diagram with a given scale factor, in a given
* WIMP redraw rectangle
*
* Parameters: draw_diag *diag -- the diagram to be rendered
* draw_redrawstr *r -- the WIMP redraw rectangle
* double scale -- scale factor
* draw_error *error -- possible error condition
*
* Returns: True if render was successful
* Other Info: The diagram must have been processed by
* draw_verify_diag(). Note that draw_redrawstr is the same
* as wimp_redrawstr, which may be cast to it.
* Very small and negative scale factors will result in a
* run-time error (safe > 0.00009). The caller should do
* range checking on the scale factor.
* Note: following the normal convention for coordinate
* mapping, the part of the diagram rendered is found by
* mapping the top left of the diagram, in draw coord space
* onto a point:
* (r->box.x0 - r->scx, r->box.y1 - r->scy)
* in screen coordinates.
*
*/
BOOL draw_render_diag(draw_diag *diag, draw_redrawstr *r, double scale,
draw_error *error);
/************************** Memory allocation functions ********************/
typedef int (*draw_allocate)(void **anchor, int n);
typedef int (*draw_extend)(void **anchor, int n);
typedef void (*draw_free)(void **anchor);
/* ---------------------- draw_registerMemoryFunctions ---------------------
* Description: Register three functions to be used to allocate, extend
* and free memory, when rendering text objects
*
* Parameters: draw_allocate alloc -- pointer to function to be used for
* memory allocation
* draw_extend extend -- pointer to function to be used for
* memory extension
* draw_free free -- pointer to function to be used for
* memory freeing.
* Returns: void.
* Other Info: These three functions will be used only when rendering text
* area objects. Any memory allocated during rendering will
* be freed (using the supplied function) after rendering.
* If draw_registerMemoryFunctions() is never called,
* or if memory allocation fails, then an attempt to render
* a text area will produce no effect.
* The three functions should operate as follows:
* int alloc(void **anchor, int n) :
* allocate n bytes of store and set *anchor
* to point to them.
* Return 0 if store can't be allocated, otherwise
* non-zero.
* int extend (void **anchor, int n):
* extend the block of memory which starts at
* *anchor to a total size of n bytes. Note that
* n will always be positive, and the new memory
* should be appended to the existing block (which
* may be moved by the operation).
* Return 0 if the memory can't be allocated, else
* non-zero.
* void free(void **anchor):
* free the block of memory which starts at
* *anchor, and set *anchor to 0.
*
* **NOTE** : The specification for these three functions is
* the same as that for flex_alloc, flex_extend
* and flex_free (in the flex module), so these
* can be used as the three required functions!!
*
*/
void draw_registerMemoryFunctions(draw_allocate alloc,
draw_extend extend,
draw_free free);
/* -------------------------- draw_shift_diag ------------------------------
* Description: Shift a diagram by a given distance.
*
* Parameters: draw_diag *diag -- the diagram to be shifted
* int xMove -- distance to shift in x direction
* int yMove -- distance to shift in y direction.
* Returns: void.
* Other Info: All coordinates in the diagram are moved by the given
* distance.
*
*/
void draw_shift_diag(draw_diag *diag, int xMove, int yMove);
/* ---------------------------- draw_querybox ------------------------------
* Description: Find the bounding box of a diagram.
*
* Parameters: draw_diag *diag -- the diagram
* draw_box *box -- the returned bounding box
* BOOL screenUnits -- indication whether the box is to be
* specified in draw or screen units.
* Returns: void.
* Other Info: The bounding box of diag is returned in box. If
* screenUnits is true, box is in screen units, else in draw
* units.
*
*/
void draw_queryBox(draw_diag *diag, draw_box *box, BOOL screenUnits);
/* ----------------------------- draw_convertBox ---------------------------
* Description: Convert a box to/from screen coordinates.
*
* Parameters: draw_box *from -- box to be converted
* draw_box *to -- converted box.
* BOOL toScreen -- should set to TRUE if conversion is to
* be from draw coords to screen coords
* FALSE means from screen coords to draw
* coords.
* Returns: void.
* Other Info: from and to may point to the same box.
*
*/
void draw_convertBox(draw_box *from, draw_box *to, BOOL toScreen);
/* --------------------------- draw_rebind_diag ----------------------------
* Description: Force the header of a diagram's bounding box to be exactly
* the union of the objects in it.
*
* Parameters: draw_diag *diag -- the diagram.
* Returns: void.
* Other Info: The diagram should have been processed by
* draw_verify_diag() first.
*
*/
void draw_rebind_diag(draw_diag *diag);
/************************ Unknown object handling **************************/
/*
* New types of object can be added by registering an unknown object handler.
* The handler is called whenever an attempt is made to render an object
* whose tag is not one of the standard ones known to DrawFile. It is passed
* a pointer to the object to be rendered (cast to a void *), and a pointer
* to a block into which to write any error status. The object pointer may
* be cast to one of the standard Draw types (defined in the object level
* interface), or to a client-defined type. If an error occurs, the handler
* must return FALSE and set up the error block; otherwise it must return
* TRUE. Unknown objects must conform to the standard convention for object
* headers, i.e. 1-word object tag; 1-word object size; 4-word bounding box.
* The unknown object handler is only called if the object is visible, i.e.
* if there is an overlap between its bounding box and the region of the
* diagram being rendered. The object size field must be correct, otherwise
* catastrophes will probably result.
*
*/
/* Type for unknown object handler */
typedef BOOL (*draw_unknown_object_handler)(void *object, void *handle,
draw_error *error);
/* ------------------------ draw_set_unknown_object_handler ----------------
* Description: Registers a function to be called when an attempt is made
* to render an object with an object tag which is not known
*
* Parameters: draw_unknown_object_handler handler -- the handler function
* void *handle -- arbitrary handle to pass to function
* Returns: The previous handler.
* Other Info: The handler can be removed by calling with 0 as a
* parameter.
*
*/
draw_unknown_object_handler draw_set_unknown_object_handler
(draw_unknown_object_handler handler, void *handle);
/* ------------------------- drawfdiag_init --------------------------------
* Description: Initialise the diagram level interface
*
* Parameters: void
* Returns: TRUE if all went OK.
* Other Info: none
*
*/
BOOL drawfdiag_init(void);
#endif
/* end drawfdiag.h */