The QGraphicsAnchorLayout

In the last post I mentioned that the new QGraphicsLayout, to be released in Qt 4.6, is already available in the public Qt git repository.

Now I’d like to give some overview of how it works and why we’re so excited about it.

To do that I’ll talk about the layouts that already existed in Qt, the Anchor Layout basic usage and finally, the situations that are better handled by the latter. From now on assume I’m talking about the QGraphicsView framework and where you read “widget” or “layout”, understand that I refer to QGraphicsWidgets and QGraphicsLayouts.

Existing QGraphicsLayouts

As of Qt 4.5, the exiting layouts available were the Linear and the Grid layouts. With those, as their names imply, users could have their widgets arranged side-by-side or in a spreadsheet-like fashion, with support for merged cells included.

It was not possible however to lay items out of the screen or overlap them, total or partially. Besides that, some cases would require several layouts to be nested in order to achieve the desired result.

The Anchor Layout concept

Previous layouts work like this: the linear layout would require you to add items to the layout in a given sequence and then those would be arranged side by side (or one on top of the other); in the grid layout the concept is similar, but items are now associated to X,Y indexes to represent the row and column where they should be inserted.

The Anchor Layout breaks with this paradigm in the sense there is no pre-defined concept of how should the items be arranged. The final position of each item is totally dependent on how you set the anchors. In other words, the anchor layout is a very, very flexible layout.

While most layouts are flexible to some extent and allow you to configure parameters like spacing between items or margins, the Anchor Layout brings flexibility to a new level. It was also our goal to make the setup process something easy. We didn’t want to expose hundreds of abstract parameters to the user, instead, we wanted to provide a high-level API and concept. Besides making the coding more rewarding, that would make it easier to translate into C++ code, the UI designers ideas and way of thinking. That’s what the anchors are about.

In this layout, each item has six anchorage points, which are Left, Right, Top, Bottom and the Horizontal and Vertical centers. The user is then responsible for connecting the anchorage points of different items to the others, and to the anchorage points of the layout itself. These connections are made through the use of the so called Anchors, that have well defined sizes.

Then, based on:

– the anchors created,
– the size hints of each item, and
– the size of the layout itself

the layout engine calculates the appropriate geometry of each widget.

Real world Anchor Layout use cases

Here at openBossa we have been involved on the development of rich-UI applications for long, and it was with that experience in mind that we started contributing with the guys from Qt on the development of the QGraphicsAnchorLayout.

Bellow you will find a few use cases of ours that were not handled by existing layouts and work fine with anchors.

Transition between screens

We often want to make a transition between two screens of the same application. Imagine the user performs an action that should hide the current screen and show another one.

In a rich UI application we probably want to animate such transition, one of the alternatives is to apply a fade-out or blur to the current screen until the new screen is seen. To achieve that, we want both screens to occupy the same position on the screen, the old one being in front of the new one (higher Z value). Then it’s just a matter of changing the opacity of the screen on the front and voilà, we have the effect.

So, how do we use a standard layout to make one widget (next screen) occupy the same position as another one (current screen)? We couldn’t do that with existing layout. With anchor is just a matter of anchoring both screens edges to the layout edges (right of item to right of layout, left to left, and so forth).

Usage of AnchorLayout to set two swallows on the same place

Usage of AnchorLayout to set two swallows on the same place.

Off-screen items

Another common trick used in UI animations is to have an off-screen item get “inside”  the screen or vice-versa. For instance, imagine a toolbar on the top of the screen that shows or hides itself in an animated way, like “walking into” or “out” of the screen. The idea here is to have two states (QStates maybe?) where the toolbar widget is on-screen in one of them, and off-screen in the other.

Again, with standard layouts we could not create this “off-screen” state. With anchors it’s just a matter of anchoring for instance, the bottom of the toolbar to the top of the layout, thus, the toolbar will sit right above the layout, ready to enter the screen (in an animated way) when necessary.

Usage of AnchorLayout to set a toolbar on or off-screen.

Usage of AnchorLayout to set a toolbar on or off-screen.

Organic setup

There are also those cases where we have several items arranged on the screen in a very organic way as drawn by the UI designers. Often it’s not practical (or possible) to define that arrangement in terms of several nested layouts. However, with a single Anchor Layout, all items can be arranged precisely.

Try it

There are other situations where such a flexible layout is helpful, however I hope the cases above exemplify the kind of problem we are trying to solve. Please, give it a try, let us know of your impressions. We really appreciate all kinds of feedback, either on usage, performance, API, features, and so forth. All of these will be taken into account so you can have a nice new tool ready for use in Qt 4.6.

Enjoy 🙂

Anchor Layout disponível no repositório do Qt 4.6

Este post é para avisá-los que o layout de âncoras do Qt, o QGraphicsAnchorLayout,  está disponível no repositório do Qt 4.6.

Para olhar o código fonte ou fazer o download de um tarball do código fonte, visite o Gitorious do Qt.

Como o nome indica, a versão atual só é compatível com o canvas Graphics View, ou seja é um QGraphicsLayout, e não um QLayout. Esta versão ainda está em desenvolvimento e possui defeitos conhecidos, especialmente quando os itens são organizados de maneira impossível. No entato melhoras virão ao longo do próximo mês, podem esperar.

Enquanto a documentação não está pronta, veja a declaracão da classe QGraphicsAnchorLayout para conhecer sua API. Logo que possível eu publicarei algum material explicando melhor o seu uso.

Como sempre, comentários são bem vindos!

Anchor Layout available in Qt 4.6 repository

This post is just to let you know that the Qt approach to Anchor Layouts, the QGraphicsAnchorLayout is available in the Qt 4.6 repository.

To browse the source or download a tarball, visit Qt Gitorious.

As the name implies, the current version is only available for the Graphics View Framework, ie. it is a QGraphicsLayout, not a QLayout. The current version is still under development and still have know issues, specially with impossible arrangements of items. You can expect improvements through the next month though.

Check the QGraphicsAnchorLayout header for its public API while documentation is not available. I’m going to post more about its usage soon as well.

Comments are always welcome!