[Okular-devel] Generic Generator for QTextDocument

[Albert Astals Cid]

A Dimecres 10 Gener 2007 17:54, Tobias Koenig va escriure:
> Hi,
>
> since we have two generators now which use a QTextDocument for layouting
> text and images I thought about extracting the common used code and put
> it into a class Okular::GenericGenerator which will be placed in core/
> so that other 3rd party developer can make use of it as well.
>
> The API would look like the following:
>
> ///////////////////////////////////////////////////////
>
> namespace Okular {
>
> class GenericGenerator;
>
> class GenericConverter : public QObject
> {
>     Q_OBJECT
>
>     public:
>         /**
>          * Creates a new generic converter.
>          */
>         GenericConverter();
>
>         /**
>          * Destroys the generic converter.
>          */
>         ~GenericConverter();
>
>         /**
>          * Returns the generated QTextDocument object.
>          */
>         virtual QTextDocument *convert( const QString &fileName ) = 0;
>
>     Q_SIGNALS:
>         /**
>          * Adds a new link object which is located between cursorBegin and
>          * cursorEnd to the generator.
>          */
>         void addLink( Link *link, int cursorBegin, int cursorEnd );
>
>         /**
>          * Adds a new title at the given level which is located as position
> to the generator. */
>         void addTitle( int level, const QString &title, const QTextBlock
> &position );
>
>         /**
>          * Adds a set of meta data to the generator.
>          */
>         void addMetaData( const QString &key, const QString &value, const
> QString &title );
>
>     private:
>         class Private;
>         Private* const d;
> };
>
> class GenericGenerator : public Generator
> {
>     friend class GenericConverter;
>
>     Q_OBJECT
>
>     public:
>         GenericGenerator( GenericConverter *converter );
>         virtual ~GenericGenerator();
>
>         .
>         .
>         .
>         .
>
>     private:
>         class Private;
>         Private* const d;
>
>         Q_PRIVATE_SLOT( d, void addLink( Link*, int, int ) )
>         Q_PRIVATE_SLOT( d, void addTitle( int, const QString&, const
> QTextBlock& ) ) Q_PRIVATE_SLOT( d, void addMetaData( const QString&, const
> QString&, const QString& ) ) };
>
> }
>
> ///////////////////////////////////////////////////////
>
> So to implement a new QTextDocument based generator you just have to do
> the following:
>
>
> class MyGenerator : public Okular::GenericGenerator
> {
>   public:
>     MyGenerator()
>
>       : Okular::GenericGenerator( new MyConverter )
>
>     {
>     }
> }
>
> and implementing the 'convert' method in MyConverter.

Seems good :-)

Just have a question, 'convert' methid is only be called once in the whole 
lifetime and Okular::GenericGenerator caches everything from there?

> To make it as easy as possible to add links, titles (toc) and meta data
> (annotations as well) the GenericConverter class can emit signals which
> take the use data as arguments together with the cursor positions in the
> QTextDocument. All the boring stuff (calculation positions -> normalized
> coordinates, creating the toc, filling DocumentSynopsis) is done by
> the GenericGenerator.
>
> One issue that crossed my plans you can see in addLink( Link*, int, int ).
> I want to pass the Link object here, so the developer can choose what
> type of link he wants to use in the Converter. However the passed object
> is use for an object rect which is deleted at every pixmapRequest, so
> passing the link here once doesn't work, because a new object is needed
> for every pixmapRequest.

I see two [ugly] solutions:

 - Keep a Link * on the Okular::GenericGenerator and always return a copy of 
it so when ~ObjectRect() happens the deleted one is not the original, ugly 
because you end up using more memory than needed

 - Add a LinkNotDeleteMe entry to the ObjectType enum of ObjectRect that is 
equivalent to Link except that the link * is not deleted on ~ObjectRect. Ugly 
because it smells like a hack to me.

Albert

>
> Does somebody have an idea how to solve this problem?
>
> Ciao,
> Tobias