Development/Tutorials/Introduction to Goya usage

Introduction to the Goya Framework usage

Tutorial Series	Goya Framework
Previous	C++, Qt, Model/View Qt Framework, KDE4 development environment
What's Next	n/a
Further Reading	n/a

Abstract

We are developing some component of our application using Model/View (check prerequisites). At some point on our development, we discover that we actually want to add widgets to our delegate, but the Model/View framework does not provide a powerful and integrated way of doing so. Here is where Goya comes to help out for this task.

We could say Goya is a layer between the view and your delegate that draws widgets with the needed options and that seem to behave as if they were real widgets, but they are fake widgets after all.

Goya is so nice mainly because it integrates pretty well with the Model/View design, and uses the Qt powerful signals and slots. Goya widgets will emit signals when something have happened to them, so you will be able to connect those signals to your app slots, and do fancy stuff without complex stuff.

A Simple Example

This example consists on a single window that will contain a list view. There will be pushbuttons only in the odd rows.

// Basic Goya includes

include <goya/goya.h>
include <goya/pushbutton.h>

// Basic Qt includes

include <QPainter>
include <QBoxLayout>
include <QListView>
include <QStringListModel>

// Basic KDE includes

include <kapplication.h>
include <kaboutdata.h>
include <kmessagebox.h>
include <kcmdlineargs.h>
include <klocalizedstring.h>
include <kicon.h>

// We define the model "MyModel" as a QStringListModel. In this very simple
// example, the class will only return strings, and the necessary widgets.
class MyModel

   : public QStringListModel

   Q_OBJECT

public:

   MyModel(QObject *parent = 0)
       : QStringListModel(parent)
   {
       // We create a Goya pushbutton, this pushbutton will be shared by all
       // rows using it, so the memory impact for 1000 rows is the same as for
       // 1 row. Since all our rows will show the same information (that
       // meaning the pushbutton will show always "More information") we
       // initialize the values here, and all rows will reuse them. In a
       // slightly more complex example we can later see how to handle this
       // when rows want for instance a different text for the pushbutton, or
       // a different icon.
       button = new Goya::PushButton(0);

       button->setText("More Information");
       button->setIcon(KIcon("help-about"));
       button->setIconSize(QSize(16, 16));

       // Goya is able to "eat events". This means that the events that you
       // specify here won't be forwarded to the view. This is pretty helpful
       // because when you click on a button that is in a non-selected row
       // and the MouseButtonPress eat is enabled, the unselected row won't
       // be selected, because the button receives that event, and "eats" it.
       button->setEatEvents(QEvent::MouseButtonPress);
       button->setEatEvents(QEvent::MouseButtonRelease);
       button->setEatEvents(QEvent::MouseButtonDblClick);

       // We would like to connect to the clicked signal of the pushbutton.
       connect(button, SIGNAL(clicked(QModelIndex,const Goya::PushButton*)),
               this, SLOT(slotClicked(QModelIndex)));
   }

   virtual ~MyModel()
   {
       delete button;
   }

   virtual QVariant data(const QModelIndex &index, int role) const
   {
       // Goya when asking for widgets asks with role WidgetRole. We teach
       // our model on what to do on this case. In this particular model, we
       // will return an empty widget list for odd rows, and a single widget
       // (our pushbutton) for even rows.
       // If the role that we were asked for is not the WidgetRole, we just
       // expect QStringListModel to do the right thing.
       if (role == Goya::WidgetRole)
       {
           if (index.row() % 2)
               return GOYA_EMPTY_WIDGET_LIST;

           return GOYA_WIDGET_LIST(button);
       }

       return QStringListModel::data(index, role);
   }

private:

   Goya::PushButton *button;

private Q_SLOTS:

   // This slot will be triggered when our pushbutton has been clicked. Note
   // that the signal has an index and even a Goya::PushButton* parameters.
   // In this case only with the index we are OK. On the messagebox we notify
   // the user which row button was clicked.
   void slotClicked(const QModelIndex &index)
   {
       KMessageBox::information(0, "More information clicked on row " +
                                QString::number(index.row() + 1),
                                "Button clicked");
   }

};
// This is our delegate. It will perform custom painting, but this a very
// important part with Goya integration. The most important thing here is that
// this delegate inherits Goya::Canvas, what inherits QAbstractItemDelegate.
class MyDelegate

   : public Goya::Canvas

{
public:

   MyDelegate(QAbstractItemView *itemView, QObject *parent = 0)
       : Canvas(itemView, parent)
   {
   }

   virtual ~MyDelegate()
   {
   }

   // Goya asks for the position of widgets. In this method you should
   // specify where do you want widget to be placed. In a slightly more
   // complex example we will see later that you can also specify your
   // position not only in absolute terms, but relative to other Goya
   // widgets.
   QPoint widgetPosition(Goya::Widget *widget, const QStyleOption *option,
                         const QModelIndex &index) const
   {
       // We will be at the topLeft corner, with a small separation from the
       // limits of the delegate of font height, for example.
       return QPoint(option->fontMetrics.height(),
                     option->fontMetrics.height());
   }

   void paint(QPainter *painter, const QStyleOptionViewItem &option,
              const QModelIndex &index) const
   {
       if (option.state & QStyle::State_Selected)
       {
           painter->fillRect(option.rect, option.palette.highlight());
       }

       painter->save();

       if (option.state & QStyle::State_Selected)
       {
           painter->setPen(QPen(option.palette.highlightedText().color()));
       }

       // In this case we want to draw the string below the button. sizeHint
       // method from Canvas will return the united rect of all widgets in
       // that row. As we only have one, is the same as asking for
       // Canvas::widgetSize with the correct parameters.
       painter->drawText(option.fontMetrics.height() + option.rect.left(),
                         option.fontMetrics.height() * 3 + 
                         Canvas::sizeHint(option, index).height() + 
                         option.rect.top(),
                         QString("This is the index in row number ") + 
                         QString::number(index.row() + 1));

       painter->restore();

       // This is very important. Do not forget to ask Goya to paint,
       // because this is the method that will actually draw the widgets
       // onto your delegate.
       Canvas::paint(painter, option, index);
   }

   QSize sizeHint(const QStyleOptionViewItem &option,
                  const QModelIndex &index) const
   {
       Q_UNUSED(option);
       Q_UNUSED(index);

       // As before, we use sizeHint, but there is no problem of using
       // widgetSize with the correct parameters.
       QSize size = Canvas::sizeHint(option, index);

       size.setWidth(size.width() + option.fontMetrics.height() * 4);
       size.setHeight(size.height() + option.fontMetrics.height() * 4);

       return size;
   }

};