muhuk's blog

Nature, to Be Commanded, Must Be Obeyed

January 30, 2009

Using Layouts In Qooxdoo - Part 1

This is the first part of a tutorial series about layout managers, container objects and object hierarchies in Qooxdoo (qx for short from here on). Its target audience is mostly qx programmers coming from an (X)HTML/CSS/DOM background who have possibly used JavaScript libraries such as JQuery or prototype before. Qx is different, it is a JavaScript RIA Framework. If you have used a GUI toolkit such as Swing (Java), wxWidgets or GTK+ you should have no difficulty following this tutorial. In fact you will probably find it boring1. On the other hand if you are still trying to find out how you can attach your <div /> in an existing qx layout; you are in the right place.

The answer is “No”, to the question above. You don’t create DOM elements with qx (unless you are doing something really exotic). Actually you don’t need to concern yourself with the DOM at all. GUI is abstracted to a set of intuitive classes that you should be familiar from today’s desktop operating systems. This abstraction brings two big advantages:

  • Developers using qx don’t need to concern themselves with cross-browser issues.
  • Theming is easy and uniform.

Widgets Are The Building Blocks

A qx user interface is constructed using widgets. A widget is a class that encapsulates appereance, data and behaviour. For instance a TextField would render itself as a box and a caret, make the text you enter inside accessible programmatically and allow you to be notified whenever a the text data is changed. Widgets are customizable, subclassable and of course themable.

But a GUI hardly ever consists of a single widget. Instead there is a hierarchy of widgets. A container is a special kind of widget that has child widgets. A container widget ususally doesn’t have any visual parts itself and just render its children in its screen space. How child widgets are positioned within their container is decided by the container’s layout manager. Having a layout manager means the abstraction of layout strategy for maximum flexibility.

So how do containers, child widgets and layout managers work together? First of all qx positions everything with absolute coordinates (Yes; position:absolute) internally. But that doesn’t mean you need to position anything absolutely on the API level. Speaking in terms of JavaScript libraries; you can take advantage of floating/auto-sizing/liquid layouts. Position and size of all widgets are negotiated through this hierarchy. Theoretically everyone has a say. This means that you can set some constraints on parents and then some others on child widgets and they all work together. The resulting layout is then converted to absolute coordinates for rendering. (Examples in the next part)


  1. Qx GUI’s are hierarchically constructed from widgets.
  2. Each application has a root container.
  3. Each container has a layout manager and one or more child widgets2.
  4. A child of a container can be either:
    1. Another container.
    2. Or a control widget (such as a form widget).

NEXT PART: VBox Layout

1: You might want to see Qooxdoo - API documentation instead.

2: Although it is possible that a container may have no children, it is not sensible.

If you have any questions, suggestions or corrections feel free to drop me a line.