Migration from qx.Desktop 2.x¶
qx.Desktop 3.0 introduces some major improvements to the internals of qooxdoo's desktop widget system. This was made possible by taking advantage of features in modern browsers while trying to implement graceful degradation in older browsers and discontinuing support for some legacy browsers.
In order to improve UI performance and decrease memory load, every widget now consists of just one content element. Before, each desktop widget consisted of (at least) two DOM elements and their JavaScript object representations: container and content. Usually widgets also had a decorator element. Now widgets no longer have decorator, container or protector elements.
Most modifications were made "under the hood", affecting mostly internal APIs. Therefore regular users should immediately benefit from those improvements without being required to adjust their application code. If custom themes and/or custom layouts are used however, some manual adjustments to existing applications based on qx.Desktop 2.x may be required. Additionally, some theming features no longer have fallback implementations for legacy browsers (see below for details).
Legacy Browsers¶
Some browsers unfortunately lack built-in functionality for some features common to modern browsers. To work around those technical limitations is either too complex or simply impossible. Therefore browser support in qx.Desktop 3.0 had to be adjusted accordingly:
- Browser versions no longer supported:
- IE 6, 7
- Firefox 3.5 and below
- Safari 3
- Opera 11 and below
- Browser versions with limited support:
- IE 8:
- double borders on input elements no longer supported
- border-image decorations no longer supported
- PNGs are no longer supported as background images in combination with the backgroundRepeat values 'scale' and 'no-repeat'
- PNGs with alpha transparency are no longer supported as background images
- IE 9, 10:
- border-image decorations no longer supported
Built-in Themes¶
Along with the changes in the qx.Desktop GUI toolkit, the themes that ship with the SDK have also been adjusted. They no longer contain the image-based fallbacks for legacy browsers that were used to work around missing CSS3 features.
- Indigo, Simple: no changes from previous releases
- Modern: shadows and rounded borders no longer available in IE 8
- Classic: shadows no longer available in IE 8; text fields and text areas only with single not double borders
This is also relevant if you used some of the decorators for your custom widgets. They might have been renamed or deleted.
Custom Themes¶
The following information applies to user-defined themes. The framework's built-in themes are already up to date.
Decoration Theme¶
- The
inset
properties of the decorators have been set to read-only. Any inset definitions in your decoration theme or application code should be removed and replaced with the correspondingpadding
and/ormargin
in the appearance theme. - The
decorator
theme key will be ignored. All decorations now use a common class, which supports all decoration features. You can simply remove anydecorator
keys from your custom theme. - The decorators
qx.ui.decoration.Grid
,qx.ui.decoration.GridDiv
,qx.ui.decoration.BoxDiv
,qx.ui.decoration.AbstractBox
,qx.ui.decoration.HBox
, andqx.ui.decoration.VBox
have been removed. These classes were responsible for providing image-based fallback implementations for border-image and background-gradient decorators, meaning border-image decorations are no longer available in Internet Explorer 8 - 10. The properties of MBorderImage provide these features for most modern browsers. Change every occurrence of thebaseImage
key to its new equivalent, borderImage. - The
qx.ui.decoration.Beveled
andqx.ui.decoration.Uniform
decorators are deprecated. Replace them withqx.ui.decoration.Decorator
and use the width, style and color properties. - The decorator
qx.ui.decoration.Double
is also deprecated. Replace it withqx.ui.decoration.Decorator
and use the properties of MDoubleBorder. qx.ui.decoration.DynamicDecorator
has been deprecated. Replace it with decoration.Decorator.
Custom Decorators¶
The qx.ui.decoration.IDecoration
interface has been updated. The methods getMarkup
, tint
and resize
were removed. getStyles
was added: This method is responsible for adding the Decorator's CSS styles to a map of existing styles.
Appearance Theme¶
- The key
shadow
is no longer supported in the map returned by thestyle
function. Use the properties ofqx.ui.decoration.MBoxShadow
instead (in the decoration theme).
Custom Layouts¶
Custom layouts extending qx.ui.layout.Abstract
must be adjusted: The renderLayout
method is now called with a map containing the container's top
, bottom
, left
and right
padding values as an additional third argument. These values must be taken into consideration when calculating the layout children's size and position.
Custom Widgets¶
The following information is only relevant for authors of custom widgets using the qx.html
layer directly.
- With the removal of the decorator element, the method
qx.ui.core.Widget.getDecoratorElement
was also removed. For most use cases it should be sufficient to use the content element instead, which can be accessed byqx.ui.core.Widget.getContentElement
. - The same applies to the container element and
qx.ui.core.Widget.getContainerElement
. This method is deprecated and returns the content element. Useqx.ui.core.Widget.getContentElement
instead. - As with the container element itself, the method
qx.ui.core.Widget.getContainerLocation
is deprecated. Just useqx.ui.core.Widget.getContentLocation
instead. - The
shadow
property has been removed. Use a decorator setting the properties ofqx.ui.decoration.MBoxShadow
instead.
Other Code Changes¶
The blocking implementation (qx.ui.core.Blocker
, qx.ui.core.MBlocker
) was simplified:
unblockContent
was removed. Useunblock
instead.isContentBlocked
was removed. UseisBlocked
instead.forceUnblockContent
was removed. UseforceUnblock
instead.
Implementation Details¶
This section lists all further internal changes. They should not be relevant for you as an application developer. Nevertheless, this information could be useful for anyone interested in the framework's internals.
- The new implementation is based on
box-sizing: border-box
. As a consequence, Internet Explorer 6 and 7 is no longer supported. - Decorations are compiled as CSS classes and applied to a central style sheet.
- Background gradients are rendered using Canvas in IE9.
- CSS clip is used to apply padding to combined images.
- For the legacy browser fallback implementation of the text fields' placeholder property, the placeholder element is attached to the field's layout parent.
- The blocker element of
qx.ui.embed.Iframe
is now attached to the application root. qx.ui.core.Blocker
is attached to the blocked widget's layout parent.- The default
zIndex
value for Widgets is now 10. qx.html.Element
now supports addition and removal of CSS classes.qx.ui.tooltip.ToolTip
offers a new child control namedarrow
. It is used to render an arrow for error tooltips in the Modern theme.- The padding of
qx.ui.basic.Image
instances is applied as background-position. - Separators are now instances of
qx.ui.core.Widget
instead ofqx.html.Element
. - The infrastructure classes
qx.ui.core.DecoratorFactory
andqx.html.Decorator
have been removed.