scbdoc.h

Go to the documentation of this file.

#ifndef SCBDOC_H_
#define SCBDOC_H_

/*
 * File Name  : scbdoc.h
 * 
 * Description: Scribble library document 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 < >
#include <libermetadb/ermetadb.h>

// local include files, between " "
#include "scbpath.h"
#include "scbpages.h"
    
#ifdef __cplusplus
extern "C"
{
#endif


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


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


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

// Maintain current state, such as current color / pen size/ pen style
// caller can update its UI widget according to doc state
//
// toolbar cmd ---> current state  ---> new style
//                       |
//                       -------------> new state
//                       |
//                       -------------> update UI by macro
// all platform related function is defined by macro
typedef enum _ScbTBState
{
    ERSCRIBBLE_TBS_NONE, 
    ERSCRIBBLE_TBS_SCRIBBLE,
    ERSCRIBBLE_TBS_SELECT_PEN_SIZE,
    ERSCRIBBLE_TBS_SELECT_LINE_COLOR,
    ERSCRIBBLE_TBS_ERASE,
    ERSCRIBBLE_TBS_INVALID
} ScbTBState;

// Map a icon to a scribble toolbar state, so that scribble library can handle toolbar request
typedef struct _ScbTBSItem
{
    ScbTBState  state;     /**< Tool bar status */
    int         iconId;    /**< Id of icon */
} ScbTBSItem;

typedef ScbTBSItem* ScbTBSItemPtr;

// Context of the scribble document instance.
// ScbDocContext maintains the necessary information when scribble lib is being used.
// This information can be used to initialize a new stroke, or reset the toolbar
typedef struct _ScbDocContext
{
    ScbStrokeAttributes  curStrokeAttr;      /**< current stroke attributes, be used in runtime */
    ScbTBState           curState;           /**< current toolbar status */
    GArray *             table;              /**< a table mapping the icon and status */
    int                  appId;              /**< current application id */
    gboolean             need_save_app;      /**< need save application data or not */
} ScbDocContext;

// Version Number
typedef struct _ScbVersion
{
    unsigned short major;                    /**< major version number */
    unsigned short minor;                    /**< minor version number */
} ScbVersion;

// Version information of the scribble library
typedef struct _ScbDocVersion
{
    ScbVersion    version_number;            /**< version number */
    GString*      company;                   /**< company name */
}ScbDocVersion;

// Screen setting of current document
typedef struct _ScbScreen
{
    unsigned int  dpi;                       /**< DPI */
    GString*      units;                     /**< Units used for calculation, such as "pixel" */
}ScbScreen;

// Scribble Document
typedef struct _ScbDoc
{
    ScbDocVersion   version;                 /**< version data */
    ScbScreen       screen;                  /**< screen data */
    ScbPath         path;                    /**< path of the target document, e.g. a pdf document*/
    ScbPages        pages;                   /**< list of the page intances */
    ScbDocContext   context;                 /**< document context */
    erMetadb        metadata_db;            /**< the pointer of metadata db */
}ScbDoc;

typedef ScbDoc * ScbDocPtr;


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


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

// Create a new scribble document instance
// @param target_doc_path path of the target document, e.g. a pdf document
// @return the created scribble document instance, return NULL if fails
ScbDocPtr erscribble_doc_new(const ScbPathPtr target_doc_path);

// Create a new scribble document instance using an existing database
// @param target_file_name name of the target document, e.g. a pdf document
// @param metadata_db the already opened metadata database for this document
// @return the created scribble document instance, return NULL if fails
ScbDocPtr erscribble_doc_new_with_database(const char *target_file_name, erMetadb metadata_db);

// Free an existing scribble document instance
// @param the scribble document instance that needs to be released
void erscribble_doc_free(ScbDocPtr doc);

// Free an existing scribble document instance but keep the database open
// @param the scribble document instance that needs to be released
void erscribble_doc_free_without_database(ScbDocPtr doc);

// Create a scribble document instance by the path of target document
// @param target_doc_path path of the target document
// @return the created scribble document instance if the record exists in DB
// otherwise return NULL
ScbDocPtr erscribble_doc_open(const ScbPathPtr target_doc_path);

// Create a scribble document instance by the path of target document
// Scribble library tries to search the record by target document path
// in metadata DB. If the record exists, create a new document based on
// the recorded setting
// @param target_file_name name of the target document
// @param metadata_db the already opened metadata database for this document
// @return the created scribble document instance if the record exists in DB
// otherwise return NULL
ScbDocPtr erscribble_doc_open_with_database(const char *target_file_name, erMetadb metadata_db);

// Save a scribble page into DB. The data of scribble page would be dumped into
// a BLOB, then stored into metadata DB as an item.
/*  memory layout of a scribble page BLOB
     --------------------------------------
     |   Version Number : unsigned short  |
     --------------------------------------
     |        Page Orientation : int      |
     --------------------------------------
     |         Page Color : ScbColor      |
     --------------------------------------
     |          Page Area : ScbRect       |
     --------------------------------------
     |         Strokes Number : int       |
     --------------------------------------
     --------------------------------------
     |    Stroke Color : unsigned long    |
     --------------------------------------
     |         Stroke Zoom : double       |
     --------------------------------------
     |          Stroke Layer : int        |
     --------------------------------------
     |            Shape ID : int          |
     --------------------------------------
     |            Size ID : int           |
     --------------------------------------
     |         Points Number : int        |
     --------------------------------------
     --------------------------------------
     |               X : int              |
     --------------------------------------
     |               Y : int              |
     --------------------------------------
     |            Pressure : int          |
     --------------------------------------
     --------------------------------------
     |               X : int              |
     --------------------------------------
     |               Y : int              |
     --------------------------------------
     |            Pressure : int          |
     --------------------------------------
     |                ...                 |
     --------------------------------------
*/
// @param doc the scribble document instance
// @param page the scribble page instance which belogs to doc
// @return return TRUE if the page is successfully saved, otherwise return FALSE
gboolean erscribble_doc_save_page(ScbDocPtr doc, ScbPagePtr page);

// Get a scribble page instance by the ID. Scribble library searches the page in its
// own cache at first. If the page is not cached, it will search the page record in
// metadata DB. Then if the record exists, a new page instance is created, otherwise
// return NULL.
// @param doc the scribble document instance
// @param id the id of the page, it acts as the start anchor
// @param pos_start the start position of the page
// @param pos_end the end position of the page
// @return return the pointer of the page instance if the page instance has been created,
// otherwise return NULL
ScbPagePtr erscribble_doc_get_page(ScbDocPtr doc, const ScbPageIdPtr id);

// Get all of the cached pages
// NOTE, this function is deprecated
// @param doc the scribble document instance
// @return return the pointer of the cached pages
ScbPagesPtr erscribble_doc_get_pages(ScbDocPtr doc);

// Get the stroke attributes which is maintained by scribble document's context
// @param doc the scribble document instance
// @return return the pointer of the document's stroke attributes
ScbStrokeAttributesPtr erscribble_doc_get_current_stroke_attributes(ScbDocPtr doc);

// Add a new scribble page instance to document's cache, if the same page(with same id)
// has been cached in advance, this operation ceases
// @param doc the scribble document instance
// @param page the page instance for adding in
// @return return true if the page has been added into the cache
gboolean erscribble_doc_add_page(ScbDocPtr doc, ScbPagePtr page);
gboolean erscribble_doc_insert_page(ScbDocPtr doc, ScbPagePtr page);
gboolean erscribble_doc_delete_page(ScbDocPtr doc, ScbPageIdPtr pid);


// Add a new toolbar item into context's table
// NOTE, this function is deprecated
void erscribble_doc_add_map_item(ScbDocPtr doc, const ScbTBSItemPtr ptr);

// Estimate whether it is scribbling now
// @param doc the scribble document instance
// @return return true if it is scribbling
gboolean erscribble_state_is_scribble(ScbDocPtr doc);

// Estimate whether it is erasing now
// @param doc the scribble document instance
// @return return true if it is erasing
gboolean erscribble_state_is_erase(ScbDocPtr doc);

// Dump the data of document
// This function can be used for debug
void erscribble_doc_dump(ScbDocPtr ptr);

void erscribble_doc_disable_autodelete(gboolean do_disable);

#ifdef __cplusplus
}
#endif

#endif