
namespace Grantlee
{

/**
  @page custom_qtextobject Handling custom QTextObjects

  It is possible using the QTextObjectInterface API to construct QTextDocuments containing custom text objects. If processing a QTextDocument
  containing custom objects through the MarkupDirector and AbstractMarkupBuilder classes, it is necessary to implement support for the custom types
  in %Grantlee.

  In this example, we create a builder with a new method <tt>addAudioTag</tt>. As it may be desired to implement multiple builders
  with support for the <tt>addAudioTag</tt> method, it makes sense to put that call into an interface.

  @code
    class AbstractAudioBuilder : virtual public Grantlee::AbstractMarkupBuilder
    {
    public:
      virtual void addAudioTag( const QString &source ) = 0;
    };
  @endcode

  We create a small interface for supporting the addition of audio markup. The interface should inherit virtually from the
  AbstractMarkupBuilder interface, so that functionality from through that interface is also available.

  Customized builders inheriting from an existing builder and the new interface can then be created.

  @code
    class AudioTextHtmlBuilder : public Grantlee::TextHTMLBuilder, public AbstractAudioBuilder
    {
    public:
      AudioTextHtmlBuilder();

      /* reimp */ void addAudioTag( const QString &source );
    };

    class AudioPlainTextBuilder : public Grantlee::PlainTextMarkupBuilder, public AbstractAudioBuilder
    {
    public:
      AudioPlainTextBuilder();

      /* reimp */ void addAudioTag( const QString &source );
    };
  @endcode

  The implementation of each concrete builder is appropriate to the type of markup being created.

  @code
    void AudioTextHtmlBuilder::addAudioTag( const QString &source )
    {
      appendRawText( QString( "<audio src=\"%1\" />").arg( source ) );
    }

    void AudioPlainTextBuilder::addAudioTag(const QString& source)
    {
      int ref = addReference( source );
      appendRawText( QString( "[%1]" ).arg( ref ) );
    }
  @endcode

  The final part to be implemented is support for the custom type in a MarkupDirector.
  The MarkupDirector::processCustomFragment method is called for any QTextFragments with custom QTextFormat types. This method can be implemented
  to instruct the builder to create appropriate output for the type.

  @code
    class AudioTextDocumentDirector : public Grantlee::MarkupDirector
    {
    public:

      AudioTextDocumentDirector(AbstractAudioBuilder* builder);

      /* reimp */ void processCustomFragment( const QTextFragment& fragment, const QTextDocument* doc);

    private:
      AbstractAudioBuilder *m_builder;
    };
  @endcode

  We create a subclass of Grantlee::MarkupDirector to take our new <tt>AbstractAudioBuilder</tt> interface and implement the processCustomFragment method to handle QTextFragments with our custom format type. The name of the audio file referenced in the document is then extracted and used as a parameter in the <tt>addAudioTag</tt> method.

  @code
    AudioTextDocumentDirector::AudioTextDocumentDirector(AbstractAudioBuilder* builder)
      : MarkupDirector(builder), m_builder(builder)
    {

    }

    void AudioTextDocumentDirector::processCustomFragment(const QTextFragment& fragment, const QTextDocument* doc)
    {
      if ( fragment.charFormat().objectType() != AudioType )
        return Grantlee::MarkupDirector::processCustomFragment( fragment, doc );

      QString name = fragment.charFormat().property( AudioProperty ).toString();

      m_builder->addAudioTag( name );
    }
  @endcode

  The custom AudioTextDocumentDirector and builders can then be used to create output including markup for custom types.

  @code
    AudioTextHtmlBuilder *builder = new AudioTextHtmlBuilder();
    AudioTextDocumentDirector *director = new AudioTextDocumentDirector(builder);

    director->processDocument(document);
    QString result = builder->getResult();
  @endcode

  In a simple case, this could create output such as:

  @verbatim
    <p>Here is a paragraph with an inline audio element: <audio src="http://www.example.com/mysound.ogg" />.

    <p>And another paragraph.
  @endverbatim

  or if the AudioPlainTextBuilder was used instead:

  @verbatim
    Here is a paragraph with an inline audio element: [1].

    And another paragraph.

    ----
    [1] http://www.example.com/mysound.ogg
  @endverbatim

  The textedit example in the %Grantlee source distribution implements this feature.
*/

}
