Overview of visibility and widget creation related things in qooxdoo. The new version brings much more control to the qooxdoo application developer. Many new events, many new interfaces, ...

There are two properties for visibility handling, visibility and display. Despite their names they are only loosely related to the CSS properties of the same name.

The first new property “visibility” should be used for fast show/hide-like effects for a widget. This property simply accepts the boolean values true or false.

The other new property is “display”. And now it gets a bit complex. As you know we are working hard to optimize qooxdoo especially concerning the overall performance. qooxdoo only creates (and layouts) widgets as HTML nodes when they become visible for the visitor (yeah, qooxdoo is lazy). The display property should be used whenever the toggling of the visibility (not the property mentioned above) of the widget has an effect on the parent widget. You can also initially set display to false, if you don’t want to create your widget during the initialisation of your qooxdoo application.

There are also some utility methods:

// Show your widget (create nodes and layout if not already done)
yourWidget.show();
 
// Hide your widget
yourWidget.hide();

both methods are especially useful to toggle the visibility of a widget.

As mentioned above visibility and display both toggle the visibility of the widget. They work like a boolean AND: A widget will only be visible if both properties are true (and the parent is visible and created).

While visibility does not exactly behave like the CSS property of the same name, it is somewhat similar. display on the other hand is closer to the css property display.

The property display completely removes the DOM node of the widget from the document. display behaves pretty much like a setParent(null), but has the benefit, that the child stays registered inside the parent widget. This is useful for collapsible lists or in cases, when you want to hide a widget temporarily but restore its position if it becomes visible again later.

If you want to omit the initial creation of a widget (i.e. creating DOM nodes) you simply set display to false. If you set visibility to false but keep display unchanged (defaults to true), then the widget will be created (again, in terms of DOM nodes) but hidden from the user. Of course, in both cases the widget is a regular qooxdoo widget instance.

As you can see, it is pretty straightforward to fine-tune your application. You can individually pre-create any widgets (e.g. instances of Menu) that are initially invisible, but can later be displayed instantaneously. Of course, the “main phase” during the startup of your qooxdoo application takes longer as it pre-creates those widgets. Anyway, this is just an option. Hopefully, your qooxdoo application will be fast enough without tweaking.

At the time the display property becomes true (or the widget will be inserted into a visible parent) the widget will be initially created and layouted. (Remember, visibility set to false does not prevent the creation of the widget.)

The default value of both properties in Widget is true. The following widgets have configured the default value of display to false:

• TabViewPage
• BarViewPage
• Popup
• Window

Returns if a children is seeable. Which means that it is really seeable for the user (you know ... the person sitting in front of the computer. ).

getChildren() returns an array with all children which have been added to your QxParent instance. getVisibleChildren() returns an array with only the seeable (in terms of isSeeable() children.

On the creation of the DOM node of a widget there is an event named create which you could attached an event listener to in order to do some stuff on the element creation (insert HTML, append children, ...).

There are four events:

• beforeAppear: Before a widget becomes seeable.
• appear: Directly after the widget becomes seeable.
• beforeDisappear: Before a widget becomes invisible.
• disappear: Directly after a widget becomes invisible.

Every time a widget will be inserted or removed from the DOM events will be fired. These events also will be fired if any previously invisible parent of the widget is put into a visible parent or if will be removed from one. The “Dom” part in the event name means, that this event will only be fired, when the element is removed from the document (which does include removing it from the parent node, but also includes if any parent at any level will be removed from any parent which is in the document). The best is probably just to attach some corresponding event listeners to some widgets and take a look in which order they will be fired.

• beforeInsertDom: Before the element node of the widget will be inserted into the DOM
• insertDom: Directly after the element node of the widget have been inserted into the DOM
• beforeRemoveDom: Before the element node of the widget will be removed from the DOM
• removeDom: Directly after the element node of the widget has been removed from the DOM

If a widget is not already created the first event will be create. Otherwise it is identical to any later show/hide request.

Events after show():

1. create (only if not done yet)
2. beforeAppear
3. beforeInsertDom (only if it will be appended to an element)
4. insertDom (only if it is appended to an element)
5. appear

Events after hide():

1. beforeDisappear
2. beforeRemoveDom (only if it will be removed from an element)
3. removeDom (only if it is removed from an element)
4. disappear

If you only toggle the visibility, there is no DOM action required (like appendChild, removeChild, ...) and so there will be no DOM events like insertDom, removeDom, etc.