You can use the link below to vote yourself:

Related posts:

1. Why Not To Localize Community Support
2. Using Layouts In Qooxdoo – Part 1
3. Using Layouts In Qooxdoo – Index

Complete list of parts:

1. Introduction
2. VBox Layout
3. HBox Layout
4. Grid Layout
5. Basic & Canvas Layouts

Related posts:

1. Using Layouts In Qooxdoo – Part 1
2. Using Layouts In Qooxdoo – Part 2: VBox Layout
3. Using Layouts In Qooxdoo – Part 3: HBox Layout

Basic Layout Manager

qx.ui.layout.Basic layout manager positions your widgets with absolute coordinates. It doesn’t have much to offer except the freedom of manual positioning.

We supply a left and top property when we add our widgets. Following example places buttons in a circular path, like a clock.

   1 /*
   2 #asset(qooxdoolayouts/*)
   3 */
   4 qx.Class.define("qooxdoolayouts.Application",
   5 {
   6     extend: qx.application.Standalone,
   7     members: {
   8         main: function(){
   9             this.base(arguments);
  10 
  11             var main_container = new qx.ui.container.Composite();
  12 
  13             var layout_manager = new qx.ui.layout.Basic();
  14             main_container.setLayout(layout_manager);
  15 
  16             var btn_size = 50;
  17             var distance = 175;
  18             var pi2 = 2 * 3.141592;
  19             center = {
  20                 x: Math.round(qx.bom.Viewport.getWidth()/2)-btn_size/2,
  21                 y: Math.round(qx.bom.Viewport.getHeight()/2)-btn_size/2
  22             }
  23 
  24             for (var i=0; i<12; i++) {
  25                 var button = new qx.ui.form.Button("CW"+(i+1).toString());
  26                 button.setWidth(btn_size);
  27                 button.setHeight(btn_size);
  28                 var dist_x = Math.round(distance * Math.sin(-(i/12+0.5)*pi2));
  29                 var dist_y = Math.round(distance * Math.cos(-(i/12+0.5)*pi2));
  30                 main_container.add(button, {
  31                     left: center.x + dist_x,
  32                     top: center.y + dist_y
  33                 });
  34             }
  35 
  36             var application_root = this.getRoot();
  37             application_root.add(main_container);
  38         }
  39     }
  40 });

Basic Example

Nevermind the math. What is important is; this would be much harder to achieve with other, more advanced managers such as Grid.

Canvas Layout Manager

qx.ui.layout.Canvas is a slightly advanced version of Basic. Canvas lets you define margins (of all four directions) and dimensions in percentage as well as in pixels.

Canvas allows you to define all four margins. You don’t have to define all of them of course. For example if you define a top and bottom margin remaining space will be your widget’s height¹. Alternatively you can specify a bottom margin and a height for you widget. This way it will keep its position relative to container’s bottom edge.

One thing to keep in mind is margins are defined against container, not against a bounding box like DOM. Say, if you set the same left on two widgets, they’ll be stacked on top of each other if they happen to have the same vertical coordinates. The following example mimics a Grid layout using Canvas:

   1 /*
   2 #asset(qooxdoolayouts/*)
   3 */
   4 qx.Class.define("qooxdoolayouts.Application",
   5 {
   6     extend: qx.application.Standalone,
   7     members: {
   8         main: function(){
   9             this.base(arguments);
  10 
  11             var main_container = new qx.ui.container.Composite();
  12 
  13             var layout_manager = new qx.ui.layout.Canvas();
  14             main_container.setLayout(layout_manager);
  15 
  16             main_container.add(new qx.ui.form.Button("Child Widget 1"), {
  17                 left: 20,
  18                 top: 10
  19             });
  20             main_container.add(new qx.ui.form.Button("Child Widget 2"), {
  21                 left: 140,
  22                 right: 20,
  23                 top: 10
  24             });
  25             main_container.add(new qx.ui.form.Button("Child Widget 3"), {
  26                 left: 20,
  27                 top: 50,
  28                 bottom: 10
  29             });
  30             main_container.add(new qx.ui.form.Button("Child Widget 4"), {
  31                 left: 140,
  32                 right: 20,
  33                 top: 50,
  34                 bottom: 10
  35             });
  36 
  37             main_container.getChildren()[0].setWidth(100);
  38             main_container.getChildren()[2].setWidth(100);
  39 
  40             var application_root = this.getRoot();
  41             application_root.add(main_container);
  42 
  43             application_root.addListener("resize", function(e) {
  44                 main_container.set({
  45                     "width": qx.bom.Viewport.getWidth(),
  46                     "height": qx.bom.Viewport.getHeight(),
  47                 });
  48             }, this);
  49         }
  50     }
  51 });

Canvas Example 1

We set two widgets’ widths manually (see lines 37 & 38) to get all the margins (almost) equal. The first row only has top margin set, but the second row has both top and bottom margins. We have given widgets in the second row top margins taking:

• Top margin of first row
• Height of the widgets in the first row

and

• Margin between first and second rows

into account. The same thing is true for the left margin of second column. This is because, as I mentioned, margins are calculated relative to container edges.

If you need to position your controls relative to one another, like DOM positioning, you should probably look into other layout managers like Grid. A good example of a use case for Canvas can be a mapping application such as Google Maps.

As I mentioned earlier Canvas layout accepts parameters in percentages. Following example sets vertical margins in pixels but horizontal margins in percentages:

   1 /*
   2 #asset(qooxdoolayouts/*)
   3 */
   4 qx.Class.define("qooxdoolayouts.Application",
   5 {
   6     extend: qx.application.Standalone,
   7     members: {
   8         main: function(){
   9             this.base(arguments);
  10 
  11             var main_container = new qx.ui.container.Composite();
  12 
  13             var layout_manager = new qx.ui.layout.Canvas();
  14             main_container.setLayout(layout_manager);
  15 
  16             var button = new qx.ui.form.Button("Child Widget 1");
  17             button.setMinWidth(250);
  18             button.setMaxWidth(400);
  19             main_container.add(button, {
  20                 left: "30%",
  21                 right: "30%",
  22                 top: 40,
  23                 bottom: 40
  24             });
  25 
  26             var application_root = this.getRoot();
  27             application_root.add(main_container);
  28 
  29             application_root.addListener("resize", function(e) {
  30                 main_container.set({
  31                     "width": qx.bom.Viewport.getWidth(),
  32                     "height": qx.bom.Viewport.getHeight(),
  33                 });
  34             }, this);
  35         }
  36     }
  37 });

1: Whether your widget grows this high depends. Let’s say that height is reserved for your widget.

Related posts:

1. Using Layouts In Qooxdoo – Part 1
2. Using Layouts In Qooxdoo – Part 2: VBox Layout
3. Using Layouts In Qooxdoo – Part 3: HBox Layout

qx.ui.layout.Grid is like a combined VBox & Hbox. Grid supports:

• Variable width/height columns/rows.
• Cells spanning multiple columns/rows.
• Empty cells.

Grid Layout

Here is a simple application using a Grid layout:

   1 /*
   2 #asset(grid/*)
   3 */
   4 qx.Class.define("grid.Application",
   5 {
   6     extend: qx.application.Standalone,
   7     members: {
   8         main: function(){
   9             this.base(arguments);
  10 
  11             var main_container = new qx.ui.container.Composite();
  12 
  13             var layout_manager = new qx.ui.layout.Grid();
  14             main_container.setLayout(layout_manager);
  15 
  16             main_container.add(new qx.ui.form.Button("Child Widget 1"), {row: 0, column: 0});
  17             main_container.add(new qx.ui.form.Button("Child Widget 2"), {row: 0, column: 1});
  18             main_container.add(new qx.ui.form.Button("Child Widget 3"), {row: 0, column: 2});
  19             main_container.add(new qx.ui.form.Button("Child Widget 4"), {row: 1, column: 0});
  20             main_container.add(new qx.ui.form.Button("Child Widget 5"), {row: 1, column: 1});
  21             main_container.add(new qx.ui.form.Button("Child Widget 6"), {row: 1, column: 2});
  22 
  23             var application_root = this.getRoot();
  24             application_root.add(main_container);
  25         }
  26     }
  27 });

Grid Example 1

We have created an 3×2 table layout without explicitly stating row/column count. Just set your row and column layout preferences when you add your child widgets.

Try commenting out some cells to see what happens. If you, for example, comment out second (0,1) and fifth (1,1) cells the second column disappears. But missing cells are OK otherwise. You can see below the layout when third and fifth cells are commented:

Grid Example 1 - Missing Cells

Following example illustrates row/column spanning:

   1 /*
   2 #asset(grid/ *)
   3 */
   4 qx.Class.define("grid.Application",
   5 {
   6     extend: qx.application.Standalone,
   7     members: {
   8         main: function(){
   9             this.base(arguments);
  10 
  11             var main_container = new qx.ui.container.Composite();
  12 
  13             var layout_manager = new qx.ui.layout.Grid();
  14             main_container.setLayout(layout_manager);
  15 
  16             main_container.add(new qx.ui.form.Button("Child Widget 1"), {
  17                 row: 0,
  18                 column: 0,
  19                 rowSpan: 2
  20             });
  21             main_container.add(new qx.ui.form.Button("Child Widget 2"), {
  22                 row: 0,
  23                 column: 1,
  24                 colSpan: 2
  25             });
  26             main_container.add(new qx.ui.form.Button("Child Widget 3"), {
  27                 row: 1,
  28                 column: 1
  29             });
  30             main_container.add(new qx.ui.form.Button("Child Widget 4"), {
  31                 row: 1,
  32                 column: 2
  33             });
  34 
  35             var application_root = this.getRoot();
  36             application_root.add(main_container);
  37         }
  38     }
  39 });

Grid Example 2

Spanning is easy, just like HTML tables. But we set placement (row and column parameters) explicitly. We can add our widgets in any order and still get the same layout if we use the same preferences.

As I said in the beginning of this part Grid is like a combination of VBox and HBox. Therefore flexing is two dimensional:

   1 /*
   2 #asset(grid/ *)
   3 */
   4 qx.Class.define("grid.Application",
   5 {
   6     extend: qx.application.Standalone,
   7     members: {
   8         main: function(){
   9             this.base(arguments);
  10 
  11             var main_container = new qx.ui.container.Composite();
  12 
  13             var layout_manager = new qx.ui.layout.Grid();
  14             layout_manager.setRowFlex(0, 1);
  15             layout_manager.setRowFlex(1, 1);
  16             layout_manager.setColumnFlex(0, 1);
  17             layout_manager.setColumnFlex(2, 1);
  18             main_container.setLayout(layout_manager);
  19 
  20             main_container.add(new qx.ui.form.Button("Child Widget 1"), {
  21                 row: 0,
  22                 column: 0,
  23                 rowSpan: 2
  24             });
  25             main_container.add(new qx.ui.form.Button("Child Widget 2"), {
  26                 row: 0,
  27                 column: 1,
  28                 colSpan: 2
  29             });
  30             main_container.add(new qx.ui.form.Button("Child Widget 3"), {
  31                 row: 1,
  32                 column: 1
  33             });
  34             main_container.add(new qx.ui.form.Button("Child Widget 4"), {
  35                 row: 1,
  36                 column: 2
  37             });
  38 
  39             var application_root = this.getRoot();
  40             application_root.add(main_container);
  41 
  42             application_root.addListener("resize", function(e) {
  43                 main_container.set({
  44                     "width": qx.bom.Viewport.getWidth(),
  45                     "height": qx.bom.Viewport.getHeight(),
  46                 });
  47             }, this);
  48         }
  49     }
  50 });

Grid Example 3

We have set rowFlex (vertical) and columnFlex (horizontal) for specific rows/columns on the layout manager itself. Try resizing the window to see how cells react. Note that second column (column index 1) doesn’t flex horizontally.

NEXT PART: Back To Basics

Related posts:

1. Using Layouts In Qooxdoo – Part 2: VBox Layout
2. Using Layouts In Qooxdoo – Part 3: HBox Layout
3. Using Layouts In Qooxdoo – Part 1

qx.ui.layout.HBox layout manager is similar to VBox but it places its children side by side.

HBox Layout

Let us begin with a simple application:

   1 /*
   2 #asset(hbox/*)
   3 */
   4 qx.Class.define("hbox.Application",
   5 {
   6     extend: qx.application.Standalone,
   7     members: {
   8         main: function(){
   9             this.base(arguments);
  10 
  11             var main_container = new qx.ui.container.Composite();
  12 
  13             var layout_manager = new qx.ui.layout.HBox();
  14             main_container.setLayout(layout_manager);
  15 
  16             main_container.add(new qx.ui.form.Button("Child Widget 1"));
  17             main_container.add(new qx.ui.form.Button("Child Widget 2"));
  18             main_container.add(new qx.ui.form.Button("Child Widget 3"));
  19 
  20             var application_root = this.getRoot();
  21             application_root.add(main_container);
  22         }
  23     }
  24 });

HBox Example 1

Ok, nothing special here. In the next example we will see how we can apply different constraints to individual child elements:

   1 /*
   2 #asset(hbox/*)
   3 */
   4 qx.Class.define("hbox.Application",
   5 {
   6     extend: qx.application.Standalone,
   7     members: {
   8         main: function(){
   9             this.base(arguments);
  10 
  11             var main_container = new qx.ui.container.Composite();
  12 
  13             var layout_manager = new qx.ui.layout.HBox();
  14             main_container.setLayout(layout_manager);
  15 
  16             main_container.add(new qx.ui.form.Button(
  17                                            "Child Widget 1").set({width:300}));
  18             main_container.add(new qx.ui.form.Button("Child Widget 2"));
  19             main_container.add(new qx.ui.form.Button(
  20                                             "Child Widget 3").set({width:75}));
  21             main_container.add(new qx.ui.form.Button(
  22                                 "Child Widget 4 has a slightly longer title"));
  23 
  24             var application_root = this.getRoot();
  25             application_root.add(main_container);
  26         }
  27     }
  28 });

HBox Example 2

We have set some properties on child widgets here. I know, it’s a bit ugly doing it on the same line with the addition. But screen space is more expensive now on the intertubes since the economic crisis¹. The important point here is we have set width of first and third widgets explicitly. Second and fourth will be automatically sized. Also notice that the fourth widget is wider. Buttons consider length of their labels when calculating their sizes.

The container will also be auto-sized on creation. But it won’t fill the viewport since we haven’t coded this behaviour (see previous part). Next example will include this behaviour:

   1 /*
   2 #asset(hbox/*)
   3 */
   4 qx.Class.define("hbox.Application",
   5 {
   6     extend: qx.application.Standalone,
   7     members: {
   8         main: function(){
   9             this.base(arguments);
  10 
  11             var main_container = new qx.ui.container.Composite();
  12 
  13             var layout_manager = new qx.ui.layout.HBox();
  14             main_container.setLayout(layout_manager);
  15 
  16             main_container.add(new qx.ui.form.Button("Child Widget 1").set({
  17                 width: 300,
  18                 allowGrowX: true,
  19             }), {flex: 1});
  20             main_container.add(new qx.ui.form.Button("Child Widget 2").set({
  21                 minWidth: 75,
  22                 maxWidth: 200,
  23             }), {flex: 1});
  24             main_container.add(new qx.ui.form.Button("Child Widget 3").set({
  25                 width: 75,
  26                 allowGrowX: false,
  27             }), {flex: 1});
  28 
  29             var application_root = this.getRoot();
  30             application_root.add(main_container);
  31 
  32             application_root.addListener("resize", function(e) {
  33                 main_container.set({
  34                     "width": qx.bom.Viewport.getWidth(),
  35                 });
  36             }, this);
  37         }
  38     }
  39 });

HBox Example 3

We have quite a few changes this time. First of all each widget is set to flex. First and third widgets have their (different) widths explicitly set. Growing is enabled for the first² and disabled for the third. For the second widget we have created different constraints; we have set the maximum and minimum values for width.

Try resizing the window to see how each widget reacts. We should note that the second widget never goes beyond its limits. While the other two conform to fit the containers space. MinWidth and MaxWidth are stronger constraints than width.

Let’s try constraining the container’s size:

   1 /*
   2 #asset(hbox/ *)
   3 */
   4 qx.Class.define("hbox.Application",
   5 {
   6     extend: qx.application.Standalone,
   7     members: {
   8         main: function(){
   9             this.base(arguments);
  10 
  11             var main_container = new qx.ui.container.Composite();
  12 
  13             var layout_manager = new qx.ui.layout.HBox();
  14             main_container.setLayout(layout_manager);
  15             main_container.set({
  16                 maxWidth: 900,
  17                 minWidth: 400,
  18             });
  19 
  20             main_container.add(new qx.ui.form.Button("Child Widget 1").set({
  21                 width: 300,
  22                 allowGrowX: true,
  23             }), {flex: 1});
  24             main_container.add(new qx.ui.form.Button("Child Widget 2").set({
  25                 minWidth: 75,
  26                 maxWidth: 200,
  27             }), {flex: 1});
  28             main_container.add(new qx.ui.form.Button("Child Widget 3").set({
  29                 width: 75,
  30                 allowGrowX: false,
  31             }), {flex: 1});
  32 
  33             var application_root = this.getRoot();
  34             application_root.add(main_container);
  35 
  36             application_root.addListener("resize", function(e) {
  37                 main_container.set({
  38                     "width": qx.bom.Viewport.getWidth(),
  39                 });
  40             }, this);
  41         }
  42     }
  43 });

We have set the maximum and minimum width for the container widget. If you resize the window you should notice the container obeying these constraints.

VBox & HBox Wrap-up

VBox and HBox are simple layout managers. I have mostly tried to illustrate how container preferences, layout preferences and child widget preferences work together with examples. In the next chapters we’ll work on more advanced layout managers and then composite layouts with multiple containers.

NEXT PART: Grid Layout

1: This is a lame joke, I’ve just done that for the sake of brevity.

2: This is redundant. Grow and Shrink properties are true by default.

Related posts:

1. Using Layouts In Qooxdoo – Part 2: VBox Layout
2. Using Layouts In Qooxdoo – Part 4: Grid Layout
3. Using Layouts In Qooxdoo – Part 1

qx.ui.layout.VBox is a basic layout manager that places child widgets on top of each other.

VBox Layout

Let’s see how VBox lays out components on a simple application¹. All the necessary code is below:

   1 /*
   2 #asset(vbox/*)
   3 */
   4 qx.Class.define("vbox.Application",
   5 {
   6     extend: qx.application.Standalone,
   7     members: {
   8         main: function(){
   9             this.base(arguments);
  10 
  11             var main_container = new qx.ui.container.Composite();
  12 
  13             var layout_manager = new qx.ui.layout.VBox();
  14             main_container.setLayout(layout_manager);
  15 
  16             main_container.add(new qx.ui.form.Button("Child Widget 1"));
  17             main_container.add(new qx.ui.form.Button("Child Widget 2"));
  18             main_container.add(new qx.ui.form.Button("Child Widget 3"));
  19 
  20             var application_root = this.getRoot();
  21             application_root.add(main_container);
  22         }
  23     }
  24 });

VBox Example 1

I told you VBox is basic; child widgets are stacked vertically in order they have added. We haven’t set any preferences (constraints), so it’s all defaults. Buttons get an optimal width depending on the length of their label. The container main_container applies this width to itself, it conforms its children’s dimensions.

Try giving one of the buttons a longer label. Now the modified button is wider, that was expected. But the others are widened as well. That is because they have conformed (flexed) their container’s width. We will see how this works in detail.

Let’s set the container’s size same as the viewport’s:

   1 /*
   2 #asset(vbox/*)
   3 */
   4 qx.Class.define("vbox.Application",
   5 {
   6     extend: qx.application.Standalone,
   7     members: {
   8         main: function(){
   9             this.base(arguments);
  10 
  11             var main_container = new qx.ui.container.Composite();
  12             main_container.setWidth(qx.bom.Viewport.getWidth());
  13             main_container.setHeight(qx.bom.Viewport.getHeight());
  14 
  15 
  16             var layout_manager = new qx.ui.layout.VBox();
  17             main_container.setLayout(layout_manager);
  18 
  19             main_container.add(new qx.ui.form.Button("Child Widget 1"));
  20             main_container.add(new qx.ui.form.Button("Child Widget 2"));
  21             main_container.add(new qx.ui.form.Button("Child Widget 3"));
  22 
  23             var application_root = this.getRoot();
  24             application_root.add(main_container);
  25         }
  26     }
  27 });

VBox Example 2

Notice that only width seems to be adjusted, even though we have set both dimensions. Actually, it worked as we intended to; main_container now fills the entire viewport. But by default VBox won’t flex child widgets vertically. We will start overriding this behaviour in a minute.

Try setting alignY property to “center” or “bottom” on the layout manager:

layout_manager.setAlignY("bottom");

So far we have set properties (constraints) on containers (main_container.width & main_container.height) and on layout managers (layout_manager.alignY). In the next example we will set properties on child widgets:

   1 /*
   2 #asset(vbox/*)
   3 */
   4 qx.Class.define("vbox.Application",
   5 {
   6     extend: qx.application.Standalone,
   7     members: {
   8         main: function(){
   9             this.base(arguments);
  10 
  11             var main_container = new qx.ui.container.Composite();
  12             main_container.setWidth(qx.bom.Viewport.getWidth());
  13             main_container.setHeight(qx.bom.Viewport.getHeight());
  14 
  15             var layout_manager = new qx.ui.layout.VBox();
  16             main_container.setLayout(layout_manager);
  17 
  18             main_container.add(new qx.ui.form.Button("Child Widget 1"), {flex: 1});
  19             main_container.add(new qx.ui.form.Button("Child Widget 2"), {flex: 1});
  20             main_container.add(new qx.ui.form.Button("Child Widget 3"), {flex: 1});
  21 
  22             var application_root = this.getRoot();
  23             application_root.add(main_container);
  24         }
  25     }
  26 });

VBox Example 3

We have added a second parameter to the add method of layout manager. This JavaScript object literal is used to set widget specific properties on the layout manager.

Flex property determines how the extra space² is distributed between children. By default it is set to 0, which means that the widget will not grow vertically. Any other (integer) value for flex will cause growing to occupy the extra space. Growing is proportional to flex value. Try different flex values for different widgets and see the changes.

NEXT PART: HBox Layout

1: If you haven’t created a qx application before, it is explained in detail in the tutorial.

2: Remaining space after initial dimensions of children are computed.

Related posts:

1. Using Layouts In Qooxdoo – Part 3: HBox Layout
2. Using Layouts In Qooxdoo – Part 4: Grid Layout
3. Using Layouts In Qooxdoo – Part 1

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)

Recap

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 widgets².
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.

Related posts:

1. Using Layouts In Qooxdoo – Part 2: VBox Layout
2. Using Layouts In Qooxdoo – Part 3: HBox Layout
3. Using Layouts In Qooxdoo – Part 4: Grid Layout

Qooxdoo is well documented and has a clean API. It comes with a Python program to help with builds. Because it is such a big framework you test on a partially compiled source and when finished this build program generates a single (actually two, it also generates a loader), compact (and somewhat obfuscated) file for performance. I strongly advise you to give it a try. The following is a small introductory tutorial. It aims to go little further than Hello World. This is not a tutorial explaining object oriented programming concepts, I assume you are already fluent in OOP.

Create The Skeleton

Screenshot of finished application

We’ll create a simple calculator-like application. I am assuming you have downloaded (latest version is 0.8 for today) and extracted the source into a directory. Let’s call it qxtut. The first thing we will do is to create a skeleton of our application with the following command;

./qooxdoo-0.8-sdk/tool/bin/create-application.py --name basicmath

This command has created the following directory structure under ./basicmath;

qxtut/
  qooxdoo-0.8-sdk/
  basicmath/
    source/
    build/
    cache/
    api/
    config.json
    Manifest.json

Well, some of the directories (build & cache) are not there yet. But as we go on they will appear, I just wanted you to see how the application is organized. config.json and Manifest.json files are configuration files for the build tool. We don’t need to change them for this tutorial, but you are welcome to check their contents.

Let us build our source for the first time;

cd basicmath
./generate.py source

Now if you open ./source/index.html in your browser you can see a Hello World application in action. We’ll replace this with our own program. But before we proceed I’d like to point out a few things;

• When we define our classes, we call a class method define on qx.Class and pass our class’ name (along with its namespace) and its contents as arguments. We don’t define our classes using prototypes, in order to take advantage of Qooxdoo’s object oriented programming features.
• Qooxdoo supports single inheritance (with mixins). We define our base class, if we have one, using extend key.
• Instance members are defined inside the members key and class members are defined inside the statics key.
• construct and destruct are two special functions for initialization and cleanup of the class.
• Qooxdoo supports [properties](http://en.wikipedia.org/wiki/Property_(programming)) as well, but it is outside of this tutorial’s scope.
• Finally, “#asset(basicmath/*)” line tells the build program to include assets (images etc) in qxtut/basicmath/source/resource/basicmath directory.

Custom Classes

Let’s start building our application now. Here is a compact version of Application.js;

/* ************************************************************************
#asset(basicmath/*)
************************************************************************ */

qx.Class.define("basicmath.Application", {
    extend: qx.application.Standalone,
    members: {
        main: function()
        {
            this.base(arguments);
            if (qx.core.Variant.isSet("qx.debug", "on")) {
                qx.log.appender.Native;
                qx.log.appender.Console;
            }
            // Our code will come here
        }
    }
});

Now we will create a custom class named Operation. This class will take two operands and perform an operation on them, and then later we will add it the ability to report the result of the operation. Paste this as Operation.js;

/* ************************************************************************
#asset(basicmath/*)
************************************************************************ */

qx.Class.define("basicmath.Operation", {
    extend: qx.ui.container.Composite,
    construct: function() {
        this.base(arguments);
        var layout = new qx.ui.layout.HBox(6);
        this.setLayout(layout);
        this.operand1 = new qx.ui.form.TextField("0");
        this.operator = new qx.ui.form.SelectBox();
        this.operator.add(new qx.ui.form.ListItem("add"));
        this.operator.add(new qx.ui.form.ListItem("subtract"));
        this.operator.add(new qx.ui.form.ListItem("multiply"));
        this.operator.add(new qx.ui.form.ListItem("divide"));
        this.operand2 = new qx.ui.form.TextField("0");
        this.result = new qx.ui.basic.Label("0");
        this.add(this.operand1);
        this.add(this.operator);
        this.add(this.operand2);
        this.add(this.result);
    },
    members: {
        operand1: null,
        operator: null,
        operand2: null,
        result: null
    }
});

The code should be self explanatory. Notice here, we define operand1, operator, operand2 and result as members of the class. Also notice we initialize those members in the constructor and not in the class body¹. This is because their respected values (classes) are derived from the non-primitive Object type. Therefore if we have assigned them a non-primitive type (such as the array [1, 2, 3]) in the members section; all instances would point to the same object.

Let us now plug this object in our application. Replace the comment line “// Our code will come here” with the following;

this.getRoot().add(new basicmath.Operation);

Now, when we compile the source and run index.html we should see our widgets in place.

Screenshot of an Operation widget we have just created

Simple Behaviour

We want our widget to calculate the operation and show us the result. Let’s update the members section of Operation with the following;

members: {
    operand1: null,
    operator: null,
    operand2: null,
    result: null,
    updateResult: function() {
        var v1 = this.cleanField(this.operand1);
        var v2 = this.cleanField(this.operand2);
        var r;
        switch(this.operator.getValue()) {
            case "add": r = v1+v2; break;
            case "subtract": r = v1-v2; break;
            case "multiply": r = v1*v2; break;
            case "divide": r = v1/v2; break;
        }
        this.result.setContent(String(r));
        this.operand1.setValue(String(v1));
        this.operand2.setValue(String(v2));
    },
    cleanField: function(field) {
        var val = parseInt(field.getValue());
        return isNaN(val) ? 0 : val;
    }
}

We have added two functions here updateResult and cleanField. Now we make use of them, change the construct with the following;

construct: function() {
    this.base(arguments);
    var layout = new qx.ui.layout.HBox(6);
    this.setLayout(layout);
    this.operand1 = new qx.ui.form.TextField("0");
    this.operand1.addListener("input", this.updateResult, this);
    this.operator = new qx.ui.form.SelectBox();
    this.operator.add(new qx.ui.form.ListItem("add"));
    this.operator.add(new qx.ui.form.ListItem("subtract"));
    this.operator.add(new qx.ui.form.ListItem("multiply"));
    this.operator.add(new qx.ui.form.ListItem("divide"));
    this.operator.addListener("changeValue", this.updateResult, this);
    this.operand2 = new qx.ui.form.TextField("0");
    this.operand2.addListener("input", this.updateResult, this);
    this.result = new qx.ui.basic.Label("0");
    this.add(this.operand1);
    this.add(this.operator);
    this.add(this.operand2);
    this.add(this.result);
}

We just added these three listeners to update the result when an operand or the operator changes;

this.operand1.addListener("input", this.updateResult, this);
this.operator.addListener("changeValue", this.updateResult, this);
this.operand2.addListener("input", this.updateResult, this);

The last parameter (this) for addListener (even though it is sometimes unnecessary) set the scope within the listener code (the second parameter). Qooxdoo handles most of the binding automatically, I think this is included for flexibility.

Let’s compile and run again. The result of the operation should update as you change the values now.

Events To Tie All Together

I’ll give you the finished code first and then we can go over the details. Here is Operation.js;

/* ************************************************************************
#asset(basicmath/*)
#asset(qx/icon/Oxygen/*)
************************************************************************ */

qx.Class.define("basicmath.Operation", {
    extend: qx.ui.container.Composite,
    construct: function() {
        this.base(arguments);
        var layout = new qx.ui.layout.HBox(6);
        this.setLayout(layout);
        this.operand1 = new qx.ui.form.TextField("0");
        this.operand1.addListener("input", this.updateResult, this);
        this.operator = new qx.ui.form.SelectBox();
        this.operator.add(new qx.ui.form.ListItem("add"));
        this.operator.add(new qx.ui.form.ListItem("subtract"));
        this.operator.add(new qx.ui.form.ListItem("multiply"));
        this.operator.add(new qx.ui.form.ListItem("divide"));
        this.operator.addListener("changeValue", this.updateResult, this);
        this.operand2 = new qx.ui.form.TextField("0");
        this.operand2.addListener("input", this.updateResult, this);
        this.result = new qx.ui.form.TextField("0");
        this.result.setReadOnly(true);
        var close_button = new qx.ui.form.Button(
            null,
            "qx/icon/Oxygen/16/actions/application-exit.png"
        );
        close_button.addListener("execute", function(e) {
            this.fireDataEvent(
                "changeResult",
                0,
                parseFloat(this.result.getValue()),
                false
            );
            this.destroy();
        }, this);
        this.add(this.operand1);
        this.add(this.operator);
        this.add(this.operand2);
        this.add(new qx.ui.basic.Label("="));
        this.add(this.result);
        this.add(new qx.ui.core.Spacer(8));
        this.add(close_button);
    },
    events: {
        "changeResult": "qx.event.type.Data"
    },
    members: {
        operand1: null,
        operator: null,
        operand2: null,
        result: null,
        updateResult: function() {
            var v1 = this.cleanField(this.operand1);
            var v2 = this.cleanField(this.operand2);
            var r;
            switch(this.operator.getValue()) {
                case "add": r = v1+v2; break;
                case "subtract": r = v1-v2; break;
                case "multiply": r = v1*v2; break;
                case "divide": r = v1/v2; break;
            }
            this.fireDataEvent("changeResult",
                r,
                parseFloat(this.result.getValue()),
                false
            );
            this.result.setValue(String(r));
            this.operand1.setValue(String(v1));
            this.operand2.setValue(String(v2));
        },
        cleanField: function(field) {
            var val = parseInt(field.getValue());
            return isNaN(val) ? 0 : val;
        }
    }
});

And Application.js;

/* ************************************************************************
#asset(basicmath/*)
#asset(qx/icon/Oxygen/*)
************************************************************************ */

qx.Class.define("basicmath.Application", {
    extend : qx.application.Standalone,
    members : {
        main : function()
        {
            this.base(arguments);
            if (qx.core.Variant.isSet("qx.debug", "on")) {
                qx.log.appender.Native;
                qx.log.appender.Console;
            }
            var layout = new qx.ui.container.Composite(
                new qx.ui.layout.VBox(8)
            );
            var layout_footer = new qx.ui.container.Composite(
                new qx.ui.layout.HBox(6)
            );
            var total = new qx.ui.basic.Label("0");
            var add_button = new qx.ui.form.Button(
                "Add New",
                "qx/icon/Oxygen/16/actions/list-add.png"
            );
            add_button.addListener("execute", function(e) {
                var new_operation = new basicmath.Operation();
                layout.addBefore(new_operation, layout_footer);
                new_operation.addListener("changeResult", function(e) {
                    var old_total = parseFloat(total.getContent());
                    var new_total = old_total - e.getOldData() + e.getData();
                    total.setContent(String(new_total));
                }, this);
            }, this);
            layout_footer.add(add_button);
            layout_footer.add(total);
            layout.add(layout_footer);
            add_button.execute();
            this.getRoot().add(layout);
        }
    }
});

Let’s go top-down and begin with the changes in the Application.js;

var layout = new qx.ui.container.Composite(new qx.ui.layout.VBox(8));
this.getRoot().add(layout);

We don’t necessarily need to subclass everytime we need specialized behaviour. Since I had intented to re-use Operation I have it as a seperate class. But for the layout of the application I just instanciated some classes and tweaked them inside Application.main. layout here is the topmost widget, we will put everything else in it. Basically one or more Operation‘s and a footer to dispay the grand total. VBox layout is by the way a layout manager that stacks children vertically, and a HBox stacks horizontally.

var layout = new qx.ui.container.Composite(new qx.ui.layout.VBox(8));
var layout_footer = new qx.ui.container.Composite(new qx.ui.layout.HBox(6));
var total = new qx.ui.basic.Label("0");
var add_button = new qx.ui.form.Button(
    "Add New",
    "qx/icon/Oxygen/16/actions/list-add.png"
);
add_button.addListener("execute", function(e) {
    var new_operation = new basicmath.Operation();
    layout.addBefore(new_operation, layout_footer);
    new_operation.addListener("changeResult", function(e) {
        var old_total = parseFloat(total.getContent());
        var new_total = old_total - e.getOldData() + e.getData();
        total.setContent(String(new_total));
    }, this);
}, this);

We define a label total to hold the grand total of all operations and an add button for new operations. Notice the closures work on 7th line. Although we limit ourselves a little bit to take advantage of OOP, we are still in a dynamic environment. Finally we tie all these components together and finally add the layout to the application root.

add_button.execute();

This instantiates the first Operation for us. We execute the button instead of creating the widget programmatically to avoid the code duplication (see the “execute” listener on the add_button).

Now let’s take a look at the changes in Operation.js. I have replaced the result Label with a TextField (remember to run “generate.py source” each time dependencies change). I wanted to take advantage of the getOldData function on TextField‘s changeValue event. But appereantly it doesn’t supply the old data. But I kept it as a TextField anyway, setting it read-only.

Then I decided that Operation should signal for a result change (maybe this is more politically correct) and added a custom event changeResult on it.

events: {
    "changeResult": "qx.event.type.Data"
}

This event is fired inside Operation.updateResult;

this.fireDataEvent(
    "changeResult",
    r,
    parseFloat(this.result.getValue()),
    false
);

The second parameter is returned from e.getData() and the third is from e.getOldData(). Therefore we can calculate the grand total without iterating all Operations;

var new_total = old_total - e.getOldData() + e.getData();

An important point here is to fire changeResult to correct the grand total before we destroy an Operation;

close_button.addListener("execute", function(e) {
    this.fireDataEvent(
        "changeResult",
        0,
        parseFloat(this.result.getValue()),
        false
    );
    this.destroy();
}, this);

Wrapping Up

Now it should work correctly, if I haven’t made a typo of course. Let us build it with;

./generate.py build

It generates a loader (~150kb) and an application script (~400kb). You don’t need the Qooxdoo source anymore, you can just upload the contents of the build directory and your application would run.

This concludes my a little further than Hello World tutorial. If you find errors or typos, or have any questions please leave a comment here or contact me at muhuk@jabber.org.

1: Here is an explanation in Qooxdoo manual.

Related posts:

1. Using Layouts In Qooxdoo – Index
2. Using Layouts In Qooxdoo – Part 1
3. Using Layouts In Qooxdoo – Part 2: VBox Layout

I would, first of all, ask for ease of deployment. What good is a software if you can’t run it? Ease of deployment for both the clients and the server. But clients here are more important for two reasons; they will be many, and they will be installed on desktop computers in the wild. As opposed to one server, which is (hopefully) maintained by professionals. So I would like my new software to be easily installed, uninstalled and upgraded on any computer connected to my network.

I would also like to be able to access the software through any client connected. It is a bad bad security model to rely on authentication against a client installation. Each and every client should be identical and the authentication should be done against some form of credentials¹.

As a user I would also like to know that the client software will not mess with the rest of my system. Software breaking² other software, or the entire operating system is useless, no matter how much utility it has otherwise.

I guess you have realized by now where I am going with this. The system I have described above is unlikely a big over-burdened application that radiates seriousness from your screen and clings itself into the bowels of your Operating System. I am actually talking about a volatile client and server architecture. Where the client almost doesn’t exist. It exists of course. It resides on the server until you connect with your browser³, then get downloaded and run. This model is called Rich Internet Application, RIA for short.

The key characteristics of RIA are;

• No install or uninstall⁴.
• Automatic remote upgrades.
• [Sandboxed](http://en.wikipedia.org/wiki/Sandbox(computersecurity))

Rich Internet Applications are powerful and considerably easier to deploy. They do have one drawback; the platform (HTML+CSS+JavaScript) they run on is not designed for applications from the beginning. It is initially designed for documents and then extended to support for applications. The main practical problem is that the JavaScript implementations are not as fast and reliable (on high loads) as native code or other popular interpreted languages. But we have started to see a new breed of browsers specifically built for applications. I am sure JavaScript virtual machines will be improved significantly in the near future.

On the other hand benchmarking and measuring performance by actually using and application typically yields different results. In our example, business applications do not involve heavy operations that require a lot of processing power. Non-linear video editing does, image synthesis does, desktop publishing does, business applications doesn’t. So the RIA would still be my first choice even with the possible performance problems mentioned above.

More on this later.

Related posts:

1. Using Layouts In Qooxdoo – Part 1
2. Using Layouts In Qooxdoo – Part 2: VBox Layout
3. Using Layouts In Qooxdoo – Part 3: HBox Layout