drawfobj

/* 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:   drawfobj.h
 * Purpose: Processing of Draw format files (object level interface)
 *
 */

/*
 *
 * This file supplements the diagram level interface with routines for
 * dealing with individual objects.
 */

#ifndef __drawfobj_h
#define __drawfobj_h

#ifdef DRAWFILE_INTERNAL
#include "h.DrawIntern.drawcvttyp"
#else
/* Data types for specifying object details */
#ifndef __drawfdiag_h
#include "h.drawfdiag"
#endif
#ifndef __drawftypes_h
#include "h.drawftypes"
#endif
#endif

#ifndef BOOL
#define BOOL int
#define TRUE 1
#define FALSE 0
#endif



/******************************** DATA TYPES *******************************/

/*
 * Data type for specifying the full details of any object type.
 * It is used in operations on complete objects, such as creation
 * and querying, and so does not include the types needed for
 * contained structures and types, such as path elements or text
 * columns : those are defined in h.drawftypes.
 *
 */

typedef union
{
  draw_objhdr      *object;
  draw_fileheader  *fileHeader;
  draw_fontliststr *fontList;
  draw_textstr     *text;
  draw_pathstr     *path;
  draw_spristr     *sprite;
  draw_groustr     *group;
  draw_textareahdr *textarea;
  char             *bytep;
  int              *wordp;
} draw_objectType;



/* Symbolic code for no object */

#define draw_NoObject (draw_object)-1


/*
 * For functions that operate on a range of objects (and ONLY those
 * functions), the following special codes may be used to mean 'from the
 * start' and 'to the end'.
 *
 */

#define draw_FirstObject (draw_object)-1
#define draw_LastObject  (draw_object)-2



/********************************* Global data *****************************/
/* An array of 256 integers, used for font translation. Immediately after
 * a call to draw_createObject where the object was a font table, this
 * contains the mapping between old and new font reference numbers, such
 * that  transTable[old fontref] = new fontref.
 * draw_translateText makes use of this table; it is exported for
 * callers who may want to do something elaborate.
 */

extern int *draw_transTable;

/************************** Interface functions ****************************/


/* --------------------------- draw_create_diag ----------------------------
 * Description:   Create an empty diagram (ie. just the file header), with
 *                a given bounding box.
 *
 * Parameters:    draw_diag *diag -- pointer to store to hold diagram
 *                char *creator -- pointer to character string holding
 *                                 creator's name
 *                draw_box bbox -- the bounding box (in Draw units).
 * Returns:       void.
 * Other Info:    diag must point at sufficient memory to hold the diagram.
 *                The first 12 chars of creator are stored in the file
 *                header. diag.length is set appropriately by this function.
 *
 */

void draw_create_diag(draw_diag *diag, char *creator, draw_box bbox);


/* -------------------------- draw_doObjects -------------------------------
 * Description:   Render a specified range of objects from a diagram.
 *
 * Parameters:    draw_diag *diag -- the diagram
 *                draw_object start -- start of range of objects to be
 *                                     rendered
 *                draw_object end   -- end of range of objects to be rendered
 *                draw_redrawstr *r -- WIMP-style redraw rectangle
 *                double scale -- the scale factor for rendering
 *                draw_error *error -- possible error condition.
 * Returns:       TRUE if render was successful.
 * Other Info:    Parameters (except range) are used as in draw_render_diag,
 *                in diagram level module.
 *                The diagram must be verified before a call to this function
 *                If the range of objects inclues text with anti-aliasing
 *                fonts, you MUST call draw_setFontTable first.
 *                Very small (<0.00009) or negative scale factors will cause
 *                run-time errors.
 *
 */

BOOL draw_doObjects(draw_diag *diag, draw_object start, draw_object end,
                    draw_redrawstr *r, double scale, draw_error *error);


/* -------------------------- draw_setFontTable ----------------------------
 * Description:   Scans a diagram for a font table object and records it for
 *                a subsequent call of draw_doObjects.
 *
 * Parameters:    draw_diag *diag -- the diagram to be scanned.
 * Returns:       void.
 * Other Info:    This function must be called for draw_doObjects to work on
 *                a sequence of objects that includes text objects using
 *                anti-aliasing fonts, but no font table object. The font
 *                table remains valid until either a different one is
 *                encountered during a call to draw_doObjects, or until
 *                draw_render_diag is called, or until a different diagram
 *                is rendered.
 *
 */

void draw_setFontTable(draw_diag *diag);


/* -------------------------- draw_verifyObject ----------------------------
 * Description:   Verify the data for an existing object in a diagram
 *
 * Parameters:    draw_diag *diag -- the diagram
 *                draw_object object -- the object to be verified
 *                int *size -- gets set to the amount of memory occupied by
 *                             the object.
 *                draw_error *error -- possible error condition.
 * Returns:       TRUE if object found and verified.
 * Other Info:    Verifying an object ensures that its bounding box is
 *                consistent with the data in it; if not, no error is
 *                reported, but the box is made consistent, On an error, the
 *                location is relative to the start of the diagram.
 *                Note: the object's size is only returned if "size" is a
 *                non-null pointer.
 *
 */

BOOL draw_verifyObject(draw_diag *diag, draw_object object, int *size,
                       draw_error *error);


/* -------------------------- draw_createObject ----------------------------
 * Description:   Creates an object after a specified object in a given
 *                diagram.
 *
 * Parameters:    draw_diag *diag -- the diagram
 *                draw_objectType newObject -- the created object
 *                draw_object after -- the object after which the new object
 *                                     should be created
 *                BOOL rebind -- if TRUE, the bounding box of the diagram is
 *                               updated to the union of its existing value
 *                               and that of the new object
 *                draw_object *object -- new object's handle
 *                draw_error *error -- possible error condition
 * Returns:       TRUE if object was created OK
 * Other Info:    All data after the insertion point is moved down. "after"
 *                may be set to draw_FirstObject/draw_LastObject for
 *                inserting at the start/end of the diagram.
 *                Diagram must be large enough for the new data; its length
 *                field is updated.
 *                On an error, the location is not meaningful.
 *                The handle of the new object is returned in "object"
 *                If this function is used to create a font table, "after"
 *                is ignored, and the object merged with the existing one
 *                (if such exists) or inserted at the start of the diagram
 *                otherwise.  This can cause the font reference numbers to
 *                change; if a call to this function is followed by a
 *                draw_translateText(), the font change will be applied (only
 *                needed when anti-aliased fonts are used in text objects.
 *
 */

BOOL draw_createObject(draw_diag *diag, draw_objectType newObject,
                       draw_object after, BOOL rebind, draw_object *object,
                       draw_error *error);


/* ---------------------------- draw_deleteObjects -------------------------
 * Description:   Deletes the specified range of objects from a diagram.
 *
 * Parameters:    draw_diag *diag -- the diagram
 *                draw_object start -- start of range of objects to be
 *                                     deleted
 *                draw_object end   -- end of range of objects to be deleted
 *                BOOL rebind -- if set to TRUE, then the diagram's bounding
 *                               box will be set to the union of those
 *                               remaining objects
 *                draw_error *error -- possible error condition.
 * Returns:       TRUE if objects deleted successfully.
 * Other Info:    diag.length is updated appropriately.
 *
 */

BOOL draw_deleteObjects(draw_diag *diag, draw_object start, draw_object end,
                        BOOL rebind, draw_error *error);


/* ----------------------- draw_extractObject ------------------------------
 * Description:   Extracts an object from a diagram into a supplied buffer
 *
 * Parameters:    draw_diag *diag -- the diagram
 *                draw_object object -- the object to be extracted
 *                draw_objectType result -- pointer to the buffer
 *                draw_error *error -- possible error division
 * Returns:       TRUE if the object was extracted successfully.
 * Other Info:    The buffer for the result must be large enough to hold
 *                the extracted object (an object's size can be ascertained
 *                by calling draw_verifyObject()).
 *
 */

BOOL draw_extractObject(draw_diag *diag, draw_object object,
                        draw_objectType result, draw_error *error);


/* -------------------------- draw_translateText ---------------------------
 * Description:   Updates all font reference numbers for text objects
 *                following creation of a font table.
 *
 * Parameters:    draw_diag *diag -- the diagram.
 * Returns:       void.
 * Other Info:    If the font table has not been changed then this function
 *                does nothing.
 *
 */

void draw_translateText(draw_diag *diag);


/* -------------------------- drawfobj_init --------------------------------
 * Description:   Initialise the object level interface
 *
 * Parameters:    void
 * Returns:       TRUE if all went OK.
 * Other Info:    none
 *
 */

BOOL drawfobj_init(void);

#endif

/* end drawfobj.h */