scbstrokes.h

Go to the documentation of this file.

#ifndef SCBSTROKES_H_
#define SCBSTROKES_H_

/*
 * File Name  : scbstrokes.h
 * 
 * Description: Scribble library strokes list 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 < >

// ereader include files, between < >

// local include files, between " "
#include "scbstroke.h"

#ifdef __cplusplus
extern "C"
{
#endif


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


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


//----------------------------------------------------------------------------
// Type Declarations
//----------------------------------------------------------------------------

typedef struct _ScbStrokes
{
    GList * strokes;         /**< A list of strokes pointers */
} ScbStrokes;

typedef ScbStrokes * ScbStrokesPtr;


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


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

// Construct a new stroke list, the member strokes in ScbStrokes structure
// will be initialized
// @param ptr the pointer of a ScbStrokes instance
// @return return TRUE if construction succeeds
gboolean erscribble_strokes_new(ScbStrokesPtr ptr);

// Free the list as well as all of the items
// @param strokes the pointer of a ScbStrokes instance
void erscribble_strokes_free(ScbStrokesPtr strokes);

// Destory the list without freeing each item. This function is used
// when caller creates another container for existing items
// @param strokes the pointer of the ScbStrokes instance which needs to be cleared
void erscribble_strokes_clear(ScbStrokesPtr strokes);

// Get the number of strokes
// @param strokes the pointer of the ScbStrokes instance
// @return return the number of strokes
int erscribble_strokes_get_count(const ScbStrokesPtr strokes);

// Add a stroke into the strokes list
// @param strokes the pointer of the scribble strokes list
// @param stroke the instance of scribble stroke to added
void erscribble_strokes_add_stroke(ScbStrokesPtr strokes, 
                                   ScbStrokePtr stroke);

// Add a list of strokes into another list
// @param dst the pointer of destination strokes list
// @param src the pointer of source strokes list
void erscribble_strokes_add_strokes(ScbStrokesPtr dst, 
                                    const ScbStrokesPtr src);

// Detach a stroke from list without freeing stroke memory
// NOTE, caller should release memory of stroke returned
// caller can also add the return value to other stroke container
// @param strokes the strokes list which contains the target stroke
// @param stroke the target stroke which needs to be detached
// @return return the pointer of the detached stroke
ScbStrokePtr erscribble_strokes_detach_stroke(ScbStrokesPtr strokes, 
                                              ScbStrokePtr stroke);

// Hit test whether a point area(expanded by the setting of hit-test-context) intersects
// with any strokes in the list. The result is a stroke list, empty result means no intersection
// happens. Caller should call erscribble_stroke_detach to remove the stroke instance from the container
// @param strokes the pointer of strokes list used for hit test
// @param point the hit point
// @param ctx the context recording necessary setting for the hit test
// @return return a results list of strokes
ScbStrokesPtr erscribble_strokes_point_hit_test(ScbStrokesPtr strokes, 
                                                ScbDevPointPtr point,
                                                const ScbHitTestCtxPtr ctx);

// Hit test whether a line area(expanded by the setting of hit-test-context) intersects
// with any strokes in the list. The result is a stroke list, empty result means no intersection
// happens. Caller should call erscribble_stroke_detach to remove the stroke instance from the container
// @param strokes the pointer of strokes list used for hit test
// @param point1 the start hit point
// @param point2 the end hit point
// @param ctx the context recording necessary setting for the hit test
// @return return a results list of strokes
ScbStrokesPtr erscribble_strokes_line_hit_test(ScbStrokesPtr strokes, 
                                               ScbDevPointPtr point1,
                                               ScbDevPointPtr point2,
                                               const ScbHitTestCtxPtr ctx);

// Draw the erased strokes by driver(fast way)
// @param strokes the erased strokes list
void erscribble_strokes_erase_driver_draw(ScbStrokesPtr strokes);

// Dump the data of strokes list
// This function can be used for debug
void erscribble_strokes_dump(ScbStrokesPtr strokes);

// load the strokes from the stream
gboolean erscribble_strokes_load(ScbStrokesPtr strokes, ScbStreamPtr stream, const int strokes_num);

// write strokes data into memory stream
gboolean erscribble_strokes_write_stream(ScbStrokesPtr strokes, ScbStreamPtr stream);

// clear a strokes list without release memory
void erscribble_strokes_clear(ScbStrokesPtr strokes);


#ifdef __cplusplus
}
#endif

#endif