scbstroke.h

Go to the documentation of this file.

#ifndef SCBSTROKE_H_
#define SCBSTROKE_H_

/*
 * File Name  : scbstroke.h
 * 
 * Description: Scribble library stroke definition
 */

/*
 * This file is part of liberscribble.
 *
 * liberscribble is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 2 of the License, or
 * (at your option) any later version.
 *
 * liberscribble is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 */

/**
 * Copyright (C) 2008 iRex Technologies B.V.
 * All rights reserved.
 */
 

//----------------------------------------------------------------------------
// Include Files
//----------------------------------------------------------------------------

// system include files, between < >
#include <glib.h>

// ereader include files, between < >

// local include files, between " "
#include "scbcolor.h"
#include "scbpoints.h"
#include "scbtype.h"
#include "scbstream.h"

G_BEGIN_DECLS

    
//----------------------------------------------------------------------------
// Definitions
//---------------------------------------------------------------------------- 


//----------------------------------------------------------------------------
// Forward Declarations
//----------------------------------------------------------------------------


//----------------------------------------------------------------------------
// Type Declarations
//----------------------------------------------------------------------------
    
typedef struct _ScbStrokeAttributes
{
    ScbDevColor     color;          /**< Device color of the stroke */
    float           zoom;           /**< Zoom setting of the stroke */
    int             layer;          /**< Drawint layer of the stroke,
                                    "0" means drawing on the content */
    int             shape_id;       /**< ID of the drawing shape */
    int             size_id;        /**< ID of the shape size */
    int             points_number;  /**< Number of the stroke points */
} ScbStrokeAttributes;

typedef ScbStrokeAttributes * ScbStrokeAttributesPtr;

typedef struct _ScbStroke
{
    ScbStrokeAttributes attributes; /**< Attributes of the stroke */
    ScbRect             rect;       /**< Out bounding rectangle of the stroke,
                                    it can be used for hit test */
    ScbPoints           points;     /**< Scribble points list */
} ScbStroke;

typedef ScbStroke * ScbStrokePtr;

typedef struct _ScbHitTestCtx
{
    int             size;           /**< Hit test size, it is used for expand the area of
                                    a hit pint */
    double          zoom;           /**< Current zoom setting when a hit happens */
} ScbHitTestCtx;

typedef ScbHitTestCtx * ScbHitTestCtxPtr;


//----------------------------------------------------------------------------
// Global Constants
//----------------------------------------------------------------------------


//============================================================================
// Public Functions
//============================================================================

// Create a new scribble instance
// @return return the pointer of created scribble instance
ScbStrokePtr erscribble_stroke_new();

// Create a new stroke instance with specified attributes
// @param pAttr pointer of a stroke attributes instance
// @return return the pointer of a stroke instance
ScbStrokePtr erscribble_stroke_new_with_attributes(ScbStrokeAttributesPtr pAttr);

// Release a stroke instance, all of the memory it used will be freed
// @param stroke the stroke instance to be released
void erscribble_stroke_free(ScbStrokePtr stroke);

// Get the number of stroke points
// @param stroke the stroke instance
// @return return the number of stroke points
int erscribble_stroke_get_point_count(ScbStrokePtr stroke);

// Get start address of the points data
// @param stroke the stroke instance
// @return return the pointer of the first scribble point
ScbPointPtr erscribble_stroke_get_point_data(ScbStrokePtr stroke);

// Add a ScbPoint to the stroke
// @param stroke the stroke instance
// @param point the scribble point to be added
// @return return error code of the adding operation. 
int erscribble_stroke_add_point(ScbStrokePtr stroke, 
                                ScbDevPointPtr point);

// Draw the point by driver
// By using ioctl, draw operation will take about 0.2 second to 
// draw a stroke (25 points), while mouse event happens every 0.00048 second.
// In this case some points are ignored. To resolve this problem, driver records
// every point in an array and draw them when driver is ready(record 25 points every time).
// If it is the last point (for example, the hit point of mouse release), the driver
// should draw all of the recorded points whatever its number is.
// @param stroke the stroke instance
// @param point the hit point generated by the mouse event
// @param is_last_point flag indicating whether it is the last point
void erscribble_stroke_driver_draw_point(ScbStrokePtr stroke, 
                                         ScbDevPointPtr point,
                                         gboolean is_last_point);


// Draw the whole stroke according to current attributes by driver
// @param stroke the stroke to be drawn
void erscribble_stroke_driver_draw(ScbStrokePtr stroke);

// Hit test the point
// Estimate whether the hit point intersects the area of the target stroke
// @param stroke the target stroke instance
// @param point the hit pint
// @param ctx the hit test context
// @return return TRUE if the point is located in stroke area, otherwise return FALSE
gboolean erscribble_stroke_point_hit_test(ScbStrokePtr stroke, 
                                          ScbDevPointPtr point, 
                                          const ScbHitTestCtxPtr ctx);

// Hit test the line
// Estimate whether a line intersects the area of the target stroke
// @param stroke the target stroke instance
// @param point1 the start point of the line
// @param point2 the end point of the line
// @param ctx the hit test context
// @return return TRUE if the point is located in stroke area, otherwise return FALSE
gboolean erscribble_stroke_line_hit_test(ScbStrokePtr stroke, 
                                         ScbDevPointPtr point1,
                                         ScbDevPointPtr point2,
                                         const ScbHitTestCtxPtr ctx);

// Set shape id of the stroke
// @param stroke the target stroke instance
// @param shape_id the shape to be set
void erscribble_stroke_set_shape(ScbStrokePtr stroke, const int shape_id);

// Set the size id of the stroke
// @param stroke the target stroke instance
// @param size_id the size to be set
void erscribble_stroke_set_size(ScbStrokePtr stroke, const int size_id);

// Get the shape id of the stroke
// @param stroke the target stroke instance
// @return return the shape id of current stroke, return -1 if stroke is invalid
int erscribble_stroke_get_shape(ScbStrokePtr stroke);

// Get the size id of the stroke
// @param stroke the target stroke instance
// @return return the size id of current stroke, return -1 if stroke is invalid
int erscribble_stroke_get_size(ScbStrokePtr stroke);

// (DEPRECATED) Set color for a stroke
// @param stroke the target stroke instance
// @param color the color to be set
void erscribble_stroke_set_color(ScbStrokePtr stroke, const ScbDevColor color);

// (DEPRECATED) Get color of a stroke
// @param stroke the target stroke instance
// @return return the color of the stroke
ScbDevColor erscribble_stroke_get_color(ScbStrokePtr stroke);

// Dump the data of stroke
// This function can be used for debug
void erscribble_stroke_dump(ScbStrokePtr ptr);

// load a scribble stroke from memory stream
gboolean erscribble_stroke_load(ScbStrokePtr stroke, ScbStreamPtr stream);

// write a stroke to stream
gboolean erscribble_stroke_write_stream(ScbStrokePtr stroke, ScbStreamPtr stream);


G_END_DECLS

#endif