Themed Views

Templates allow an abstract 'visual look' to be declared in theme XML and then factorized and drawn to a custom user interface component.

Consider an example where we would like to theme the look of button. We can use templates to define the look of the button and then draw an instance of that look to the button.

First we define the template in Theme XML.

    <page vspath="/UIComponents">
        <template name="buttonnormal">
            <image rect="0,0,0,0" src="buttonnormalbg"/>
            <text rect="0,0,0,0" align="hcenter,vcenter">expr:@NormalText</text>
        </template>
        <template name="buttonclicked">
            <image rect="0,0,0,0" src="buttonclickedbg"/>
            <text rect="0,0,0,0" align="hcenter,vcenter">expr:@PressedText</text>
        </template>
    </page>

Then assuming the theme XML has been loaded into a ThemedView, we create a instance of the template and use it to draw our button.

    class ThemedButton : public QPushButton
    {
    private:
        ThemedView* view; // contains the loaded theme
        bool buttonPressed; // contains a flag indicating whether the button is currently pressed or not
    protected:
        void paintEvent(QPaintEvent* e)
        {
            // find our template
            QString templateName = buttonPressed ? "buttonnormal" : "buttonclicked";
            ThemeTemplateItem* template = (ThemeTemplateItem*)view->findItem(templateName, ThemedView::Template);
            Q_ASSERT(template != 0);

            // create an instance of the template
            ThemeTemplateInstanceItem* instance = template->createInstance(QString::number( (int)this )); // pass a uid to createInstace, used as value for vspath
            // paint the template instance to this widget
            QPainter p(this);
            view->paint(&p, e->rect(), instance);

            // cleaup
            delete instance;
        }
    };

The createInstance() line needs further explanation. The ThemeTemplateItem::createInstance() takes a unique identifier which is used as the vspath value for the template instance. This means each template has its own unique value space path for expressions to operate on. In this case the base valuespace path will be "/UIComponents/<uid>/" and so the text items in the template will refer to "/UIComponents/<uid>/NormalText" and "/UIComponents/<uid>/PressedText" where uid is in this case the this pointer of the class converted to a string.