Generic Embeddable plugins.

Hi Folks,
          I've taken the comments of people asking for a generic
embeddable API on-board and now propose the following.

The idea is to have a generic XP class with a well defined API with
default implementations. Plugins are subclasses of this class which
overide the default implementations.

OK here is the header file for the base class:
-------------------------------------------------------------
#ifndef __gr_Abi_EmbedManager_h__
#define __gr_Abi_EmebdManager_h__
#include "ut_string_class.h"
#include "ut_types.h"
#include "pt_Types.h"

class GR_Graphics;
class UT_ByteBuf;
class PD_Document;
class ABI_EXPORT GR_EmbedView
{
public:
  GR_EmbedView(PD_Document * pDoc, PT_AttrPropIndex api );
  virtual ~GR_EmbedView(void);
  PD_Document * m_pDoc;
  PT_AttrPropIndex m_iAPI;
  bool m_bHasSVGSnapshot;
  bool m_bHasPNGSnapshot;
  UT_ByteBuf m_SVGBuf;
  UT_ByteBuf m_PNGBuf;
}

class ABI_EXPORT GR_Abi_EmbedManager
{
public:
    GR_Abi_EmbedManager(GR_Graphics * pG);
    virtual ~GR_Abi_EmbedManager();
    const char * getObjectType(void) const;
    GR_Abi_EmbedManager * createMe(GR_Graphics * pG);
    virtual void initialize(void);
    GR_Graphics * getGraphics(void);
    virtual void setGraphics(GR_Graphics * pG);
    virtual UT_sint32 makeEmbedView(PD_Document * pDoc,
PT_AttrPropIndex api) ;
    virtual void setColor(UT_sint32 uid, UT_RGBColor c);
    virtual UT_sint32 getWidth(UT_sint32 uid);
    virtual UT_sint32 getAscent(UT_sint32 uid) ;
    virtual UT_sint32 getDescent(UT_sint32 uid) ;
    virtual void loadEmbedData(UT_sint32 uid);

    virtual void setDefaultFontSize(UT_sint32 uid, UT_sint32);
    virtual void render(UT_sint32 uid, UT_sint32 x, UT_sint32 y);
    virtual void releaseEmbedView(UT_sint32 uid);
    virtual void initializeEmbedView(UT_sint32 uid);
    virtual void makeSnapShot(UT_sint32 uid);
    virtual bool isDefault(void);
 private:
    GR_Graphics * m_pG;
    UT_Vector<GR_EmbedView *> m_vecSnapshots;
};

We will have two methods in the XAP_App class which are used to register
and discover embeddable plugins. Two register the plugin creates a copy of
the itself and calls:

XAP_App::registerEmbeddable(GR_Abi_EmbedManager * pEmbed)

Which places the pointer to this manager in a vector in XAP_App.

We have invented a new type of piecetable object like a field or image.
The object type is
PTO_Embed.

The PTO_Embed object has an attribute "object-type". The value of this
attribute is the type of embeddable object. For MathML we would have the
object/attribute pair "object-type:MathML"

When the layout classes encounter a PTO_Embed object they look in
fl_DocLayout to see if a manager has been loaded for it. If one has they
use that, otherwise a new manager is created via the XAP_App method:

GR_Abi_EmbedManager * XAP_App::getEmbeddableManager(GR_Graphics * pG,
const char * szObjectType)

This method scans the vector of loaded plugins looking for a match to
szObjectType via the

GR_Abi_EmbedManager::getObjectType(void)

method.

If a match is found a new instance of the manager is created and returned
to the caller via the

GR_Abi_EmbedManager * GR_Abi_EmbedManager::createMe(GR_Graphics * pG)

Method.

If none are found a default implementation is created and returned to
fl_DocLayout which stores it in a vector as well.

OK now we have either the default embeddable or the requested implementation.

I'll go through the rest of the API.

virtual void initialize(void);

This initializes the manager.

    GR_Graphics * getGraphics(void);
    virtual void setGraphics(GR_Graphics * pG);

As you might expect. The setGraphics method is called when the document is
zoomed.

    virtual UT_sint32 makeEmbedView(PD_Document * pDoc,
PT_AttrPropIndex api) ;

This method makes a specific instance of the render for the object in
question. It returns an integer which is an index (a "handle") to the
specific instance of the renderer. The PD_Document and PT_AttrPropIndex
index are used to determine specific attributes of the object as well as
being used to make snapshots of the renderer.

    virtual void setColor(UT_sint32 uid, UT_RGBColor c);
    virtual UT_sint32 getWidth(UT_sint32 uid);
    virtual UT_sint32 getAscent(UT_sint32 uid) ;
    virtual UT_sint32 getDescent(UT_sint32 uid) ;
    virtual void setDefaultFontSize(UT_sint32 uid, UT_sint32);

These do as expected.

    virtual void loadEmbedData(UT_sint32 uid);

OK these load the data from data-item in the associated with the object.
This data could be:

MathML for a the GtkMathView plugin
Gnumeric XML for a Gnumeric plugin
Postscript text for a postscript plugin

Some generic bonobo XML data for a generic bonobo plugin.
Whatever you like...

    virtual void render(UT_sint32 uid, UT_sint32 x, UT_sint32 y);

Draw the object at locattion (x,y) in the graphics class.

    virtual void releaseEmbedView(UT_sint32 uid);

Delete this specific renderer

    virtual void initializeEmbedView(UT_sint32 uid);
Initialize a specific instance of this view.

    virtual void makeSnapShot(UT_sint32 uid);

Make a snapshot of the current view. This snapshot can be either in SVG or
PNG form. SVG is clearly prefered. The snapshot data is stored in the
PD_Document as a data item. The attribute/value is recorded for the
PTO_Embed object as either

"snapshot-svg:dataitem-val#" or "snapshot-png:dataitem-val#"

Where dataitem-val# is some unique string to identify the object.

If idea is that if a document loaded by an instance of AbiWord without the
plugin, the default implementation can render the snapshot of the object.

I will make a PNG snapshotter for which just takes a screenshot of the
object.

Once the SVG backend for gnome-print is in wide use, and printable
document which employs gnome-print can be snapshotted.

    virtual bool isDefault(void);

Returns true if the manager is the default implementation.

Here is my current working of the MathML plugin header file...

Cheers

Martin

-----------------------------------------------------------------------

#include "ut_string_class.h"
#include "gr_Abi_EmbedManager.h"
#include <MathView/libxml2_MathView.hh>

class GR_Graphics;
class GR_Abi_MathGraphicDevice;
class GR_Abi_RenderingContext;
class MathMLOperatorDictionary;
class GR_AbiMathView;

class ABI_EXPORT GR_Abi_MathManager : pubic GR_Abi_EmbedManager
{
public:
    GR_Abi_MathManager(GR_Graphics * pG);
    virtual ~GR_Abi_MathManager();
    GR_Abi_EmbedManager * createMe(GR_Graphics * pG);
    virtual void initialize(void);
    GR_Graphics * getGraphics(void);
    virtual void setGraphics(GR_Graphics * pG);
    virtual UT_sint32 makeEmbedView(PD_Document * pDoc,
PT_AttrPropIndex api) ;
    virtual void setColor(UT_sint32 uid, UT_RGBColor c);
    virtual UT_sint32 getWidth(UT_sint32 uid);
    virtual UT_sint32 getAscent(UT_sint32 uid) ;
    virtual UT_sint32 getDescent(UT_sint32 uid) ;
    virtual void loadEmbedData(UT_sint32 uid, UT_UTF8String &
sMathBuf);
    virtual void render(UT_sint32 uid, UT_sint32 x, UT_sint32 y);
    virtual void releaseEmbedView(UT_sint32 uid);
    virtual void initializeEmbedView(UT_sint32 uid);
    virtual void makeSnapShot(UT_sint32 uid);
    virtual bool isDefault(void);
private:
    virtual UT_sint32 _makeMathView(void) ;
    virtual void _releaseMathView(UT_sint32 uid);
    virtual void _resetRootElement(UT_sint32 uid, void);
    virtual void _loadMathML(UT_sint32 uid, UT_UTF8String &
sMathBuf);
    UT_sint32 _getNextUID(void);
    UT_sint32 m_CurrentUID;
    SmartPtr<AbstractLogger> m_pLogger;
    SmartPtr<GR_Abi_MathGraphicDevice> m_pMathGraphicDevice;
    GR_Abi_RenderingContext * m_pAbiContext;
    SmartPtr<MathMLOperatorDictionary> m_pOperatorDictionary;
    UT_Vector<GR_AbiMathView *> m_vecMathView;
};
Received on Tue Jan 11 04:18:25 2005