Today, I’m announcing a new project open for development: QFacebook. It consists of a Qt port of the Facebook Graph API.

The interest in creating this project came from another one that we are currently working on at INDT. We needed to access and manage Facebook accounts, but we didn’t want to use the old rest API.

There are three non-C++ solutions available: the official Javascript SDK from Facebook, a PHP SDK and a Python SDK. Seeing the lack of a Qt port for this API we decided to make our own library.

The project is hosted at gitorious and the the URL is:

• http://gitorious.org/qfacebook

As of now, the project has two usage examples that you can start coding with. But we are still working on the documentation.

Anyone is welcome use it or even join our development effort.

Lets expand this idea and create a customized widget on Graphics View. The simplest widget of them all is the Push Button (actually the simplest widget is the Label, but then, I wouldn’t have much to write on this post ).

The Button widget has the following characteristics:

1. Display 2 images depending on its state (normal & pressed);
2. Detects mouse clicks (including moving the mouse while clicked);

On to the coding part…

There’s only one attribute for storing the Button’s state: m_isPressed. Depending on the value of m_isPressed, the paint() method will either draw one of two QPixmap objects, m_normal or m_pressed.

Here’s the paint() method for the Button class:

void Button::paint(QPainter *painter,
                   const QStyleOptionGraphicsItem *option,
                   QWidget *widget)
{
    Q_UNUSED(option);
    Q_UNUSED(widget);
 
    if (m_isPressed)
        painter->drawPixmap(0, 0, m_pressed);
    else
        painter->drawPixmap(0, 0, m_normal);
}

The change between the normal and pressed image happens through the mouse handling methods. Here’s the mousePressEvent() method:

void Button::mousePressEvent(QGraphicsSceneMouseEvent *event)
{
    if (event->button() == Qt::LeftButton) {
        if (contains(event->pos()))
            m_isPressed = true;
 
        update();
    }
}

If the user clicks within the image area, m_isPressed is set. Therefore, the pressed image is displayed.

Now the mouseMoveEvent() method:

void Button::mouseMoveEvent(QGraphicsSceneMouseEvent *event)
{
    if (event->buttons() & Qt::LeftButton) {
        if (contains(event->pos())) {
            m_isPressed = true;
        } else {
            m_isPressed = false;
        }
 
        update();
    }
}

It the user moves the mouse (while clicking) to outside the image area, m_isPressed is changed.

And finally, the mouseReleaseEvent() method:

void Button::mouseReleaseEvent(QGraphicsSceneMouseEvent *event)
{
    if (event->button() == Qt::LeftButton) {
        m_isPressed = false;
 
        update();
 
        if (contains(event->pos())) {
            emit clicked();
        }
    }
}

The m_isPressed attribute is unset and the clicked() signal is emitted (if the mouse stays within the image area).
Here’s the customized Button in action:

The source code for this example is at my gitorious repository, under the button dir:

http://gitorious.org/tech-blog/sources/trees/master/button

Because the image is a rounded one, there are some parts “outside” of the Button that also receive mouse events. This happens because we still need to determine the “clickable” area through the shape() method. But that’s something for another post.

Till next time.

To take out some of the dust from the blog ,  I figured we could start with something simple like handling events on the GraphicsView framework.

It works like this: The view (QGraphicsView) receives events and passes them to the scene (QGraphicsScene). In order to pass these events to the scene, the view must first convert these units (pixel coordinates) into scene units (vertex coordinates). This conversion process is transparent, but you access these coordinates through convenience methods like mapFromScene and mapToScene. This also applies for the inverse path (passing events from the scene to the view).

Now, let’s say you want to capture mouse events. To do that, you have to reimplement the mousePressEvent and/or mouseReleaseEvent methods. Depending on your needs, they can be reimplemented from within the QGraphicsItem class (handling single items) or the QGraphicsScene class (handling the whole scene).

Here’s an example (I’ve used the class from the previous post as reference):

void CustomItem::mousePressEvent(QGraphicsSceneMouseEvent *event)
{
  qDebug() << "Mouse button clicked at position: "
           << event->pos();
}
 
void CustomItem::mouseReleaseEvent(QGraphicsSceneMouseEvent *event)
{
  qDebug() << "Mouse button released at position: "
           << event->pos();
}

Every time you click on the item, it will display a clicked message, and every time you release the mouse, it will display a released message. These methods are called whenever the desired event happens (Mouse presses, Mouse releases, Mouse moves, Key presses, Key releases, etc).

The QGraphicsSceneMouseEvent is the mouse event object. It’s a similar class to the QMouseEvent class, except that it only handles the QGraphicsView mouse events and not QWidget events.

There are also other handling methods like: mouseMoveEvent and mouseDoubleClickEvent for mouse events or keyPressEvent and keyReleaseEvent for keyboard events. For the keyboard ones, the item must be able to receive keyboard focus (QGraphicsItem::ItemIsFocusable flag set). You just need to reimplement them as in the code above.

And that’s it. I’ve also moved my previous examples (plus this one) to a repository at the Qt Gitorious.

The URL is http://gitorious.org/tech-blog/sources.

The example from this post is under the handling-events dir.

In order to do that, you must first subclass from QGraphicsItem class. There are two important methods to be reimplemented:

• boundingRect: virtual function that returns the area that needs to be painted. All items have a bounding rectangle and QGraphicsView uses this function to determine what parts need to be redrawn.
• paint: virtual function that implements the painting method itself. It uses a QPainter object.

Let’s take a look at a sample code:

class CustomItem : public QGraphicsItem
{
public:
    CustomItem(QGraphicsItem *parent = 0);
 
    QRectF boundingRect() const
    {
        return QRectF(0, 0, 250, 250);
    }
 
    void paint(QPainter *painter,
               const QStyleOptionGraphicsItem *option,
               QWidget *widget)
    {
        painter->setRenderHint(QPainter::Antialiasing);
        painter->setBrush(Qt::blue);
        painter->drawRoundedRect(0, 0, 250, 250, 5, 5);
    }
};

As you can see, the boundingRect method returns a QRectF object containing the draw area. Inside the paint method, we set the brush color to blue and draw a rounded rectangle of same size as the bounding rectangle. Also, the Antialiasing flag is enabled so that the engine draw smooth edges.

There are 2 more parameters in the paint method: QStyleOptionGraphicsItem and QWidget. The first is the style option for the item and the second is an optional parameter that describes the widget to draw the item.

The QPainter parameter is the most important one right now. But, as you become more acquainted with the Qt Canvas Programming, you should look further into the other 2 parameters, specially the QStyleOptionGraphicsItem.

After adding the item (CustomItem class) to the scene and displaying it, the result is this:

Custom item drawn from QGraphicsItem.

There are several options to choose from when drawing an item with the QPainter object. You just have to replace the drawRoundedRect method with the another suitable one. There are a couple of examples below:

QPainter draw methods.

The source code used for this post is available here: custom-qgraphicsitem.tar.gz. Use it to create your customized QGraphicsItems.

Till next time.

First, you need to understand the Coordinate System. There are 3 coordinate systems in use with the framework: View coordinates, Scene coordinates and Item coordinates.

1. The View coordinate system: represents the QGraphicsView widget coordinates. Each unit in this system corresponds to one pixel on the screen.
2. The Scene coordinate system: represents logical units of a QGraphicsScene. Top-level items on the scene are positioned using this system before mapping to the View.
3. The Item coordinate system: represents the QGraphicsItem local coordinates. These coordinates are centered (by default) around the Item’s (0, 0) point.

Two example scenarios are demonstrated below:

LEFT: Untransformed View. RIGHT: Zoomed Out View. Each pixel on the View correspond to 4 logical units on the Scene. (This is only a demonstrative example)

The picture on the LEFT shows a sample scene (QGraphicsScene) visualized by an untransformed view (QGraphicsView). The picture on the RIGHT shows the same scene, but the view is changed. It has a ZOOM OUT operation applied to it.

Notice that each logical unit on the RIGHT scene does not represent a pixel on the screen anymore. However, each item remains with the SAME coordinates and bounding rectangles.

Now, let’s do some coding. First, we add a rectangle and a circle to the scene:

QGraphicsScene scene(0, 0, 240, 120);
 
QGraphicsRectItem *rect;
rect = new QGraphicsRectItem(QRect(0, 0, 100, 100));
rect->setBrush( Qt::red );
rect->setPos(10, 10);
 
scene.addItem(rect);
 
QGraphicsEllipseItem *circle;
circle = new QGraphicsEllipseItem(QRect(0, 0, 100, 100));
circle->setBrush( Qt::blue );
circle->setPos(120, 10);
 
scene.addItem(circle);
 
QGraphicsView view(&scene);
 
view.show();

A rectangle and a circle. No transformations applied.

To add both items, the addItem method was used. Both bounding rectangles start at (0, 0) point, but their scene positions were changed through the setPos method. You can still use the convenience methods to add items if you want (addRect, addEllipse, addPolygon, etc).

In order to add a third item, we must enlarge the scene to visualize it.

QGraphicsScene scene(0, 0, 240, 200);

QPolygonF polygon;
polygon << QPointF(0, 60) << QPointF(120, 60)
                          << QPointF(60, 0);
QGraphicsPolygonItem *triangle;
triangle = new QGraphicsPolygonItem(polygon);
triangle->setBrush( Qt::green );
triangle->setPos(60, 120);
 
scene.addItem(triangle);
...

A triangle (QGraphicsPolygonItem) added to the scene.

The triangle was created with the QGraphicsPolygonItem class.  A QPolygonF with the vertices is passed to its constructor.

Now, let’s apply some operations to them:

rect->translate(15, 10);
rect->rotate(10);
 
circle->translate(20, 30);
circle->scale(1/1.5, 1/1.5);
 
triangle->shear(0.85, 0);
...

Items rotated, translated, scaled and sheared.

Now the rectangle was moved and rotated (by default Qt sets the transformation center to the scene’s (0,0) point), the circle was moved and scaled (shrinked) and the triangle was sheared. You can learn more about transformations on this link: QGraphicsItem class.

And that’s it. Hope this was usefull. The source code used for this post is available here: qgraphicsitem-examples.tar.gz

In Qt, it is possible to create your own widgets through the standard provided classes like QPushButton, QCheckBox, QGroupBox, etc. But even these widgets have limitations when writing a fully customizable application. Taking into account that most applications are built around Two-dimensional canvas, Qt Software developed the Graphics View framework, namely QGraphicsView.

QGraphicsView was preceded by the former two-dimensional canvas, QCanvas. The framework is composed by 3 main elements:

1. QGraphicsView: a class for displaying the widgets of a scene; It represents a viewport.
2. QGraphicsScene: a class for storing the widgets, handling event propagation(input from mouse, keyboard and other devices) and managing item states. It represents a scene with items in it;
3. QGraphicsItem: a basic class for the graphical items on the scene. It can also represent a group of items.

A QGraphicsScene object is flexible enough to include any number of QGraphicsItem objects and still mantain the efficiency in retrieving them. On the other hand, a QGraphicsView object size is limited by the computer’s display size(1280×1024, 1024×768, 800×600, etc). Putting these 3 elements together we have something like this:

A sample composition of the QGraphicsView. Notice that the entire scene(QGraphicsScene) is not seen on the viewport.

The idea is to manage the events of each item you create and redraw them as needed. This way, you can make your own widgets with more visually appealing features.

Now, let’s take a look at a small example:

QGraphicsScene scene;
 
scene.addText("Hello, world!", QFont("Times", 10, QFont::Bold));
 
QGraphicsView view(&scene);
view.show();

In the code above, I’ve created a QGraphicsScene object and added a text to it through the convenience function QGraphicsScene::addText. The type of the item added is a QGraphicsTextItem. Then a QGraphicsView object is created to display the scene. And the result is:

Hello World example.

Let’s modify it a little bit:

QGraphicsScene scene;
 
QPainterPath path;
path.moveTo(10, 30);
path.cubicTo(80, 0, 50, 50, 80, 80);
 
scene.addPath(path, QPen(Qt::black), QBrush(Qt::green));
 
scene.addText("Hello, world!", QFont("Times", 10, QFont::Bold));
 
QGraphicsView view(&scene);
view.show();

Now I’ve also added a path to scene. This particular path creates a Bezier curve in green color. To create the path, it’s used the QPainterPath class, which allows you to draw any shape you want. And like the addText function, there’s also a QGraphicsScene::addPath convenience function. The result is:

Hello World example with a Path item.

Every QGraphicsItem on the scene can also be translated, rotated, scaled and sheared. The QGraphicsView class also supports these four operations.

And that’s it. Next time I’ll show some more advanced examples of the framework usage.