Warning, /frameworks/ktexttemplate/docs/generictypes.dox is written in an unsupported language. File is not indexed.

 namespace KTextTemplate
 {
 
 /**
 
   @page generic_types_and_templates Generic type and template support
 
   @section generic_types Generic type support
 
   %KTextTemplate offers powerful support for using any type or container in a QVariant as part of the Context.
   %Qt introspection based on Q_PROPERTY is the most convenient way to access properties on QObject derived type or types decorated with the <tt>Q_GADGET</tt> macro.
   However, sometimes it is necessary to use classes which do can't have Q_PROPERTY macros (perhaps because they are defined in third-party headers)
   and where it would not be practical to create QObject/<tt>Q_GADGET</tt> wrappers around all related classes.
 
   In such cases the metatype can be registered with %KTextTemplate and an introspection method can be written.
 
   @code
     // Non-QObject
     class Person
     {
     public:
       Person() :age(0) {}
       Person(const QString &name, int age)
         : m_name(name), m_age(age)
       {
       }
 
       QString name() const
       {
         return m_name;
       }
 
       int age() const
       {
         return m_age;
       }
 
     private:
       QString m_name;
       int m_age;
     };
 
     // Make it possible to put Person in a QVariant.
     Q_DECLARE_METATYPE(Person)
 
     // Read-only introspection of Person object.
     KTEXTTEMPLATE_BEGIN_LOOKUP(Person)
       if ( property == "name" )
         return object.name();
       else if ( property == "age" )
         return object.age();
     KTEXTTEMPLATE_END_LOOKUP
 
     void someInitializer()
     {
       // Register the Person type with the %KTextTemplate introspection system.
       KTextTemplate::registerMetaType<Person>();
     }
 
     KTextTemplate::Context getContext()
     {
       KTextTemplate::Context c;
       Person leader("The Leader", 19);
 
       QList<Person> followers;
       for (int i = 0; i < 3; ++i)
       {
         Person follower("Follower" + QString::number(i), 18);
         people.append(follower);
       }
 
       c.insert("leader", QVariant::fromValue(leader));
       c.insert("followers", QVariant::fromValue(followers));
       return c;
     }
 
     QString createOutput()
     {
       Template t = m_engine->newTemplate(
         "<h1>{{ leader.name }}</h1>"
         "<ul>"
         "{% for person in followers %}"
           "<li>{{ person.name }}, {{ person.age }}</li>"
         "{% endfor %}"
         "</ul>"
         );
 
       Context c = getContext();
 
       return t->render(&c);
     }
   @endcode
 
   There are several necessary steps and consequences.
   @li The type must be registered as a QMetaType with <tt>Q_DECLARE_METATYPE</tt>. Note that this is not needed for QObject derived types.
   @li All containers are supported. (See @ref generic_containers)
   @li The <tt>KTEXTTEMPLATE_BEGIN_LOOKUP</tt> and <tt>KTEXTTEMPLATE_END_LOOKUP</tt> macros help to define the introspection of the type. Between them is the definition of a method with the signature <tt>QVariant&nbsp;getProperty(const&nbsp;Type&nbsp;&object,&nbsp;const&nbsp;QString&nbsp;&property)</tt>.
   @li KTextTemplate::registerMetaType must be called at some point in the program before attempting to use the type in a Context.
   @li The Context is created and used as normal.
 
   @section generic_containers Generic container support
 
   %KTextTemplate supports most %Qt and STL containers by default if they are registered with the QMetaType system as shown in @ref generic_types.
   Where a container does not have built in support it can easily be added (See @ref third_party_containers).
 
   The following containers have built in support:
 
   @li QList&lt;T&gt;
   @li QList&lt;T&gt;
   @li QSet&lt;T&gt;
   @li QLinkedList&lt;T&gt;
   @li QStack&lt;T&gt;
   @li QQueue&lt;T&gt;
   @li std::vector&lt;T&gt;
   @li std::deque&lt;T&gt;
   @li std::list&lt;T&gt;
   @li QHash&lt;QString, T&gt;
   @li QHash&lt;qint16, T&gt;
   @li QHash&lt;qint32, T&gt;
   @li QHash&lt;qint64, T&gt;
   @li QHash&lt;quint16, T&gt;
   @li QHash&lt;quint32, T&gt;
   @li QHash&lt;quint64, T&gt;
   @li QMap&lt;QString, T&gt;
   @li QMap&lt;qint16, T&gt;
   @li QMap&lt;qint32, T&gt;
   @li QMap&lt;qint64, T&gt;
   @li QMap&lt;quint16, T&gt;
   @li QMap&lt;quint32, T&gt;
   @li QMap&lt;quint64, T&gt;
   @li std::map&lt;QString, T&gt;
   @li std::map&lt;qint16, T&gt;
   @li std::map&lt;qint32, T&gt;
   @li std::map&lt;qint64, T&gt;
   @li std::map&lt;quint16, T&gt;
   @li std::map&lt;quint32, T&gt;
   @li std::map&lt;quint64, T&gt;
 
   where T is one of
 
   @li bool
   @li qint16
   @li qint32
   @li qint64
   @li quint16
   @li quint32
   @li quint64
   @li float
   @li double
   @li QVariant
   @li QString
   @li QDateTime
   @li A pointer to a type which inherits QObject
   @li Any type registered with KTextTemplate::registerMetaType
   @li Any supported container
 
   Note that QSet&lt;T&gt; is an exception and will only work with types for which <tt>qHash(T)</tt> is defined. This means that QSet&lt;QVariant&gt;
   is not possible for example.
 
   Note also that containers of pointers to QObject derived types can be stored in containers, and they do not need to be explicitly
   registered with %KTextTemplate. Where the class has sufficient <tt>Q_PROPERTY</tt>s defined, the introspection method described above with
   <tt>KTEXTTEMPLATE_BEGIN_LOOKUP</tt> and <tt>KTEXTTEMPLATE_END_LOOKUP</tt> is also not necessary. Note also that any type or container can be used through a <tt>Q_PROPERTY</tt>.
 
   @code
     class PersonObject : public QObject
     {
       Q_OBJECT
       Q_PROPERTY(QString name READ name)
       Q_PROPERTY(int age READ age)
     public:
       PersonObject(const QString &name, int age, QObject *parent = 0);
 
       QString name() const;
       int age() const;
     };
 
     class SportsClub : public QObject
     {
       Q_OBJECT
       Q_PROPERTY(QString name READ name)
       Q_PROPERTY(QString sport READ sport)
       Q_PROPERTY(std::vector<QObject*> members READ members)
     public:
       SportsClub(const QString &name, const QString &sport, QObject *parent = 0);
 
       QString name() const;
       QString sport() const;
       std::vector<QObject*> members() const;
       void setMembers(std::vector<QObject*> members);
     };
 
     void someInitializer()
     {
       // QObject* already has built in support. No need to register the types
       // with KTextTemplate::registerMetaType
     }
 
     KTextTemplate::Context SomeClass::getContext()
     {
       KTextTemplate::Context c;
 
       QSet<QObject*> clubs;
       {
         auto club = new SportsClub("Smithfield Tennis Club", "Tennis", this);
 
         std::vector<QObject*> members;
         {
           auto member = new PersonObject("Alice", 21, this);
           members.push_back(member);
         }
         {
           auto member = new PersonObject("Bob", 22, this);
           members.push_back(member);
         }
         club.setMembers(members);
       }
 
       // ... specify other clubs and members
 
       c.insert("sportsClubs", QVariant::fromValue(clubs));
       return c;
     }
 
     QString createOutput()
     {
       auto t = m_engine->newTemplate(
         "{% regroup sportsClubs by sport as groupedSports %}"
         "{% for groupedClub in groupedSports %}"
           "<h1>{{ groupedClub.grouper }}</h1>"
           "{% for club in groupedClub.list %}"
             "<h2>{{ club.name }}</h2>"
             "<ul>"
             "{% for member in club.members %}"
               "<li>{{ member.name, }}, {{ member.age }}"
             "{% endfor %}"
           "</ul>"
           "{% endfor %}"
         "{% endfor %}"
         );
 
       auto c = getContext();
 
       return t->render(&c);
     }
   @endcode
 
   @see <a href="http://docs.djangoproject.com/en/1.9/ref/templates/builtins/#regroup">The regroup tag</a>
 
   The output would be something like
 
   @verbatim
     <h1>Tennis</h1>
       <h2>Smithfield Tennis Club</h2>
       <ul>
         <li>Alice, 21</li>
         <li>Bob, 22</li>
       </ul>
       <h2>Greenore Lawn Tennis and Fitness Club</h2>
       <ul>
         <li>Charlie, 23</li>
         <li>David, 24</li>
         <li>Elaine, 25</li>
         <li>Frank, 26</li>
       </ul>
     <h1>Basketball</h1>
       <h2>Sandyford Basketball Club</h2>
       <ul>
         <li>Gilian, 27</li>
         <li>Henry, 28</li>
       </ul>
   @endverbatim
 
   Of course, it is possible to use containers of pointers to concrete QObject subclasses, such as QSet&lt;PersonObject*&gt; and std::vector&lt;SportsClub*&gt; too.
 
   Because any supported container can also be used as a contained type, nested containers such as <tt>QList<QList<PersonObject*>></tt> are also supported.
 
   Note that if a type is registered with KTextTemplate::registerMetaType, built in containers of that type do not also need to be registered.
   Third party containers do need to be registered however (See @ref third_party_containers)
 
   @code
     Q_DECLARE_METATYPE(Person)
 
     void someInitializer()
     {
       KTextTemplate::registerMetaType<Person>();
 
       // Now any of the nested containers can be put 
       // in a Context and used in a Template.
     }
   @endcode
 
   @section third_party_containers Third party containers
 
   To support another, non-built in container it is necessary to use some macros to register it with %KTextTemplate.
 
   For a sequential container, <tt>Q_DECLARE_SEQUENTIAL_CONTAINER_METATYPE</tt>,
   and <tt>Q_DECLARE_ASSOCIATIVE_CONTAINER_METATYPE</tt> are needed.
 
   @code
     #include <boost/circular_buffer>
 
     // Enable looping over the contents of the container
     Q_DECLARE_SEQUENTIAL_CONTAINER_METATYPE(boost::circular_buffer)
 
     Q_DECLARE_METATYPE(boost::circular_buffer<Person>)
 
     void someInitializer()
     {
       KTextTemplate::registerMetaType<Person>();
     }
 
     KTextTemplate::Context getContext()
     {
       KTextTemplate::Context c;
 
       boost::circular_buffer<Person> buffer(5);
       // loop
       {
         Person p("Grant", 21);
         b.push_back(p);
       }
       c.insert("people", QVariant::fromValue(buffer));
     }
   @endcode
 
   @see @ref lookups
 
   For associative containers <tt>Q_DECLARE_ASSOCIATIVE_CONTAINER_METATYPE</tt> is needed.
 
   @section smart_pointers Smart Pointers
 
   Shared pointer types containing a custom type should be introspected as normal using <tt>KTEXTTEMPLATE_BEGIN_LOOKUP</tt> and <tt>KTEXTTEMPLATE_END_LOOKUP</tt>
 
   @code
     Q_DECLARE_METATYPE(QSharedPointer<Person>)
 
     void someInitializer()
     {
       KTextTemplate::registerMetaType<QSharedPointer<Person> >();
     }
 
     KTEXTTEMPLATE_BEGIN_LOOKUP(QSharedPointer<Person>)
       if (property == "name")
         return object->name();
     KTEXTTEMPLATE_END_LOOKUP
   @endcode
 
   Note that if only shared pointers to the type is in your introspectable API you only need to define the property access for the
   shared pointer. In the case above, there is no need to use <tt>Q_DECLARE_METATYPE</tt> or <tt>KTEXTTEMPLATE_BEGIN_LOOKUP</tt> with <tt>Person</tt> or <tt>Person*</tt>.
 
   This is of course true of any smart pointer:
 
   @code
     Q_DECLARE_METATYPE(boost::shared_ptr<Person>)
 
     KTEXTTEMPLATE_BEGIN_LOOKUP(boost::shared_ptr<Person>)
       if (property == "name")
         return object->name();
     KTEXTTEMPLATE_END_LOOKUP
   @endcode
 
   QSharedPointers containing QObject derived types get special treatment.
 
   QObjects are automatically introspected for their <tt>Q_PROPERTY</tt>s (See @ref custom_objects).
 
   If you have QSharedPointer&lt;PersonObject&gt; where <tt>PersonObject</tt> is derived from QObject it will be automatically
   introspected just like a QObject* is without requiring the <tt>KTEXTTEMPLATE_BEGIN_LOOKUP</tt> and <tt>KTEXTTEMPLATE_END_LOOKUP</tt> macros,
   the <tt>Q_DECLARE_METATYPE</tt> macro, or registration with the %KTextTemplate metatype system. All of the access registration
   is handled by %Qt.
 
   @code
     void getContext()
     {
       KTextTemplate::Context c;
       auto p = QSharedPointer<PersonObject>::create();
       c.insert("person", QVariant::fromValue(p));
       return c;
     }
 
     QString createOutput()
     {
       // Uses Q_PROPERTYs defined on PersonObject for name and age
       auto t = m_engine->newTemplate( "{{ person.name }}, {{ person.age }}" );
 
       auto c = getContext();
 
       return t->render(&c);
     }
   @endcode
 
   The same technique can be used to support QObject derived types in third party shared pointers, but that requires
   an extra macro, <tt>Q_DECLARE_SMART_POINTER_METATYPE</tt>.
 
   @code
     Q_DECLARE_SMART_POINTER_METATYPE(boost::shared_ptr)
 
     void getContext()
     {
       KTextTemplate::Context c;
       boost::shared_ptr<PersonObject> p( new PersonObject );
       c.insert("person", QVariant::fromValue(p));
       return c;
     }
   @endcode
 
 */
 
 }