scbpage.h

Go to the documentation of this file.

#ifndef SCBPAGE_H_
#define SCBPAGE_H_

/*
 * File Name  : scbpage.h
 * 
 * Description: Scribble library page 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 "scbconfig.h"
#include "scbstream.h"
#include "scbstrokes.h"

#ifdef __cplusplus
extern "C"
{
#endif


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


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


//----------------------------------------------------------------------------
// Type Declarations
//----------------------------------------------------------------------------
    
typedef struct _ScbPageId
{
    char   id[ERSCRIBBLE_MAX_PAGEID_LEN];    /**< id of the page, equal to the start anchor of page */
    int    position;                         /**< file position of the page,
                                           current it is equal to page number */
    gint64 annotation_id;                    /**< annotation id of the page,
                                           it is used for query data in metadat DB
                                           Caller should NOT modify this value */
} ScbPageId;

typedef ScbPageId * ScbPageIdPtr;

typedef struct _ScbPageStyle
{
    int             orientation;           /**< Orientation of a page, e.g. 0, 90, 270 */
    ScbColor        bgColor;               /**< Background color of a page */
} ScbPageStyle;

typedef struct _ScbPageOptHist
{
    // TODO. maybe a list of operation history is needed
    int a;
} ScbPageOptHist;

// Erase context. This context is used for recording necessary information when tring to
// erase a stroke. There are two erase mode in real scenario: in "Point" mode, only one point
// is considered as the erase area, the actual erasing function does the hit test with this
// point; in "Line" mode, a line with two points is considered as the erase area, the erasing
// function does the hit test with this line.
typedef struct _ScbPageEraseCtx
{
    ScbDevPoint     p1;             /**< start point of an erase line. */
    ScbDevPoint     p2;             /**< end point of an erase line */
    double          zoom;           /**< zoom setting of the erasing */
    gboolean        bInit;          /**< Indicates whether the context has been set before,
                                         if bInit is true, it means point p1 has been set, then scribble
                                         library does hit test in "Point" mode; otherwise, p1 and p2 are
                                         both set, library does hit test in "Line" mode */
} ScbPageEraseCtx;

typedef ScbPageEraseCtx * ScbPageEraseCtxPtr;

typedef struct _ScbPageAttributes
{
    unsigned short  minor_version;    /**< minor version number of the scribble library */
    ScbPageStyle    style;            /**< page style */
    ScbRect         area;             /**< page area  */
    int             strokes_number;   /**< number of the strokes in a page */
} ScbPageAttributes;

typedef struct _ScbPage
{
    ScbPageAttributes attributes;     /**< page attributes */
    ScbPageId         id;             /**< page id */
    ScbPageOptHist    actions;        /**< actions list which records the recent operations */
    ScbStrokes        strokes;        /**< stroke list of the page */
    ScbStrokes        del_strokes;     /**< deleted stroke list of the page */
    int               timestamp;      /**< timestamp of last access to this page. */
    gboolean          is_blob_loaded; /**< if the blob of a page has been loaded, erscribble need
                                           not acess the metadb again */
} ScbPage;

typedef ScbPage * ScbPagePtr;


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


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

// Construct an empty scribble page
// @return return the pointer of created page instance
ScbPagePtr erscribble_page_new();

// Set the size to the page
void erscribble_page_set_size(ScbPagePtr ptr, const int width, const int height);

// Free a page instance
// @param ptr the page instance that needs to be deleted
void erscribble_page_free(ScbPagePtr ptr);

// Clear strokes of a page
// @param ptr the page instance on which strokes should be cleared.
void erscribble_page_clear_strokes(ScbPagePtr ptr);

// Set ID of a page
// @param page the instance of the scribble page
// @param id the id to be set
void erscribble_page_copy_id(ScbPageIdPtr dst, const ScbPageIdPtr src);

// Generate a page id by page anchor, file position and the annotation id.
// @param ptr the pointer of page id instance
// @param position the file position of the page
// @param anchor the start anchor of the page
void erscribble_page_set_id(ScbPageIdPtr ptr, const int position, const char *anchor, const int anno_id);

// Reset a page id to the initial status
// @param ptr the pointer of the page id instance
void erscribble_page_reset_id(ScbPageIdPtr ptr);

// Get the number of strokes in a page
// @param ptr the pointer of scribble page instance
// @return return the number of strokes
int erscribble_page_get_stroke_count(ScbPagePtr ptr);

// Add a stroke into the scribble page
// @param page the pointer of a scribble page instance
// @param stroke the pointer of a scribble stroke
// @return return TRUE if the stroke is successfully added into the page
gboolean erscribble_page_add_stroke(ScbPagePtr page, ScbStrokePtr stroke);

// Get the address of strokes list in a scribble page
// @param page the pointer of a scribble page instance
// @return return the pointer of strokes list
ScbStrokesPtr erscribble_page_get_strokes(ScbPagePtr page);

// Initialize an erase context
// @param ptr the pointer of an erase context
void erscribble_page_erase_init(ScbPageEraseCtxPtr ptr);

// Make hit test when caller needs erase a stroke or some strokes
// @param page the pointer of a scribble page instance
// @param point the point used for hit test
// @param ptr the context of current erase operation, if a point is maintained in advance,
// the composite line will be used for hit test
// @return return a list of strokes instance if hit test succeeds, other wise return NULL
ScbStrokesPtr erscribble_page_erase_hit_test(ScbPagePtr page, ScbDevPointPtr point, ScbPageEraseCtxPtr ptr);

gboolean erscribble_page_load(ScbPagePtr page, ScbStreamPtr stream);
gboolean erscribble_page_write_stream(ScbPagePtr page, ScbStreamPtr stream);
int erscribble_page_get_length(ScbPagePtr ptr);
void erscribble_page_set_minor_version_number(ScbPagePtr page, const unsigned short minor);

// Dump the data of page
// This function can be used for debug
void erscribble_page_dump(ScbPagePtr ptr);


#ifdef __cplusplus
}
#endif

#endif