Skip navigation links
This is the reference documentation for JWt.

See: Description

Package Description
JWt main package, this package contains all JWt widgets (except for Chart and Auth widgets).
JWt Auth package, this package contains all widgets and classes related to JWt's authentication module.
JWt Chart package, this package contains all widgets and classes related to charts.
JWt Render package, this package contains all widgets and classes related to JWt's XHTML rendering module.
JWt Servlet package, this package contains some servlet class wrappers.
JWt Utils package, this package contains some utility functions, most of them are used by JWt internals.
This is the reference documentation for JWt.

Release notes

This page lists important notes on migrating existing applications to newer version of Wt. It lists changes in the library that may break the way you build Wt, the way you configure Wt or the Wt API and behaviour. It also indicates the main changes from version to verison.

Release 3.3.9 (November 21, 2017)

This release consists entirely of bug fixes.

Release 3.3.8 (August 16, 2017)

This release consists of bug fixes, and adds one new feature:

OpenID Connect support
As we've previously announced on our blog, JWt now supports OpenID Connect. All you need to do to use any OpenID Connect based service is configure a Wt::Auth::OidcService. You can also make your own OpenID Connect identity provider.

Release 3.3.7 (March 31, 2017)

This release fixes many bugs, but also introduces some new features:

Added support for WebSockets (JSR-356) in JWt.
Wt has had support for WebSockets in its wthttp connector for a while, and now it has finally arrived in JWt. This can be enabled in WtServlet#init using getConfiguration().setWebSocketsEnabled(true).
The WFileDropWidget is a new widget that allows you to upload a file or multiple files by dragging them onto an area.
Scroll visibility
Some applications require you to know whether a widget is currently visible within the viewport, or whether it is scrolled out of view, e.g. to load more content as you scroll down the page. You can now enable scroll visibility detection with WWidget#setScrollVisibilityEnabled(boolean), and react to changes in visibility with WWidget#scrollVisibilityChanged(). A new scrollvisibility feature example has been added to demonstrate this infinite scrolling application.
Touch events
Although Wt already supported touch interactions in the charting library, touch events were previously not exposed by Wt. Now, we've added WTouchEvent, and the touchStarted, touchEnded, and touchMoved events have been added to WInteractWidget. Also, draggable widgets can now also be dragged after a long press, and you can select a range using a double touch in WTableView and WTreeView.
Wraparound for WSpinBox and WTimeEdit
WSpinBox will now wrap around from its maximum to its minimum if you enable wraparound. WTimeEdit will take advantage of this feature by default.
Some minor extra features:

Release 3.3.6 (July 13, 2016)

This release has a focus on bug fixes and some new features:

Time entry improvements
WTimeEdit now supports AM/PM in its format, WTimeValidator now allows to select a minimum and maximum time and supports multiple formats, WTimePicker can now work up to millisecond precision, and is now rendered with spinboxes.
Scroll position
It's now possible to retrieve the scroll position of a WContainerWidget with getScrollTop() and getScrollLeft().
The JPA UserDatabase implementation now compares e-mail addresses case insensitively. The AuthService can be passed in the constructor, so the UserDatabase knows whether the IdentityPolicy is EmailAddressIdentity.
Charting library
There have been many bug fixes and improvements to the charting library and the interactive features introduced in Wt 3.3.5:

Release 3.3.5 (Dec 31, 2015)

This release has comes with a slew bug fixes but also one or two new features:

WCartesianChart has several new features that allow interaction with the chart without server roundtrips. These features include zoom, pan, crosshair and follow curve functionality. This is only available if the chart is drawn on an HTML canvas. This is the default rendering method on modern browsers. When enabled, the crosshair will follow mouse movement, and show in the top right corner the coordinate (according to X axis and the first Y axis) corresponding to this position.
WAxisSliderWidget lets you easily focus on a particular range by selecting an XAxis. It will create a sliding widget where you can change the size of the focused region by dragging the blue handles, and change the position by dragging the selected area. When using touch, the size of this area can also be changed using a pinch movement.
WPainter, WJavascriptHandle, WCanvasDevice
Support client-side interaction (when rendered with WCanvasPaintDevice) by using a WTransform which you can manipulate client side using a WJavascriptHandle A WJavaScriptHandle allows to access and modify an object in JavaScript. This is useful to avoid server roundtrips when frequently updating something,
WAnchor target type moved to WLink
Before, the WAnchor was the owner of the TargetType, however from now on, WLink has the ownership of the TargetType. This may break WAnchors in existing applications if the WAnchor target type is set before setting a WLink to the WAnchor.
WLink added new TargetDownload
The new TargetDownload type will allow the user to download a file without openning a new windows or tab as it was done before. This is done with the HTML5 download attribute or, if not supported by targeting a hidden iFrame contained in the page.
Added seconds to WTimePicker
WTimePicker was missing the seconds, we've also added the setSecondStep() method.
Before it was only possible to set the partial state of the WCheckbox when creating the Widget. We've added a method WCheckBox::setPartialStateSelectable(bool) which will allow the user to select indeterminate state. This is false by default;
New client side connection monitor
The WApplication::setConnectionMonitor() method will let the user register a Javascript object that will be notified on connection changes (connection, disconnection, websockets enabled/disabled..) The monitor will trigger the onChange method of the provided Javascript object
Support custom tags for widgets
We've added WWebWidget::setHtmlTagName() that will change the current html tag to the one provided. This allows the user to create widgets that are not provided by Wt, for example an iframe.

Release 3.3.4 (Mar 25, 2015)

This release has a focus on bug fixes but also one or two new new features, of which the following are the most notable:

This new proxy model simply forwards the structure of the source model, without any transformation, and can be used for implementing proxy models that reimplement data(), but retain all other characteristics of the source model.
Up till now, a chart axis was a value class, but this has been changed now: an axis is now a polymorphic class and its behaviour can now be extended (e.g. to change the way its labels are being defined).
Until now, you were responsible for configuring the padding around the chart area to accomodate for axis labels, titles, and legend. While this is still the default behaviour, we added an option to let the chart derive the required padding (using approximate font-metrics available server-side).
Several new features in 3D charts.

Release 3.3.3 (May 27, 2014)

This release has a focus on bug fixes but also one or two new new features:

Improved Meta header support.
Because WApplication meta header API was restricted to only work in certain circumstances, we have now added the ability to define meta headers (with the option to apply them to specific user agents) also in the Configuration object.
This function is an alternative to setToolTip(), useful when a tooltip text is not trivial to fetch or create. Using this function, the tool tip (HTML) text can now be loaded on-demand instead of needing to be preset on (each) widget. This also works for tooltips set from a WAbstractItemModel using the new ItemHasDeferredTooltip item flag.
Support for input masks was added, which guides the user to enter data in the correct format.

Release 3.3.2 (March 12, 2014)

This release brings a few big new features, as well the usual small improvements and bug fixes.

A) New classes:

WGLWidget provides support for 3D graphics. It provides a single API to either client-side WebGL or server-side OpenGL rendering, all hardware-accelerated. For server-side support, you will need to get and install the applicable Jogl JNI libraries for your system.
3D Charts (WCartesian3DChart, ...)
A 3D charting library was added, based on WGLWidget, and integrated with the existing 2D charting framework.

B) Main improvements:

Support for bootstrap version 3 was added, so now you have the choice between bootstrap version 2 or 3. Needless to say, you should probably target version 3 for new development work if you can live with its restricted browser support.

C) Non-backwards compatible changes

WDatePicker, WDateEdit
The date pickers will now default to interpreting a single click as a date selection and also closing the calendar.

Release 3.3.1 (October 15, 2013)

This release has a focus on bug fixes and other cleanups after the big changes that went into 3.3.0.

A) Main improvements:

The combo box now interprets LevelRole data to display headers (using HTML <optgroup< elements). Another improvement is that now the combobox saves its single selection while the model is updated.
Modal dialogs can now be created and destroyed in any order without confusing the 'silk screen'. We now also consistently interpret an enter press in the dialog to invoke the default button added to the dialog footer (if there is one).
Several improvements include the ability to indicate what buttons are the default and escape buttons with setDefaultButton() or button.setDefault() and setEscapeButton(), and the (long overdue) implementation of icons!
We've added support for TinyMCE 4.
Render library
We've added a CSS style sheet parser which will parse and apply style rules in <style> blocks (or loaded through the API), and expanded CSS support to much improvemed table rendering (including border-collapse border model and repeated table headers), relative/absolute positioning, and page-break-before/after support.

B) Non-backwards compatible changes

The getButtons() method has been renamed to getStandardButtons(), and getButtons() now return the actual list of added buttons.

Release 3.3.0 (April 8, 2013)

This release focusses on a reorganization of JWt's theme infrastructure, with the objective of supporting Twitter's Bootstrap CSS framework as a new theme. At the same time we've added a number of widgets for which Twitter Bootstrap provides styling.

It is our intention to support the Bootstrap theme (or more specifically, the Bootstrap class names) alongside the themes we already supported (which are based on our own class names). Ignoring what Bootstrap brings, you should be able to upgrade to this release without too much trouble, although you may need to adapt some CSS stylesheets as we did reorganize a number of things which were required for Bootstrap and were a good idea for our own CSS stlesheets too.

A) New classes:

WTheme, WCssTheme, WBootstrapTheme,
Theme support classes for JWt. The role of a theme is to:
  • Load the CSS stylesheets for a new session
  • Annotate newly created widgets with appropriate style classes
Functionally almost the same as a WDatePicker, this class specializes WLineEdit and is thus a WFormWidget, making it much easier to use in WTemplateFormView.
A navigation bar styles a menu as a typical top-level bar (currently only styled in the Bootstrap Theme).
A base class to simplify the creation of popup widgets that typically assist in editing or provide circumstancial information for another widget.
A split button, which combines a button and a popup menu (currently only styled in the Bootstrap Theme).
A button tool bar (currently only styled in the Bootstrap Theme)

B) Main improvements:

WDatePicker, WSuggestionPopup
The setGlobalPopup() functionality has been deprecated and does no longer have any effect, since a new improved algorithm is being used to anchor the popup to the DOM which no longer requires this workaround.
Addition of a getFooter() method that returns a container for dialog footer elements, typically buttons.
Addition of a getValidator() function that returns the validator for a field set using setValidator(),
A push button can now act as a toggle button, using setCheckable() and related API (currently only styled in the Bootstrap Theme) and can be linked to a popup menu using setMenu().
When switching between current widgets, the stacked widget will now record and restore the current scroll position, providing a much improved user experience when using the stacked widget for the 'main' contents of an application.
Full support was added for storing data of all roles, lifting the requirement to use another model such as WStandardItemModel for simple MVC widgets like WComboBox or WSuggestionPopup simply to be able to store UserRole data.
Added a new standard function (Functions.block) which allows the definition and use of a macro block inside a placeholder, which is in particular useful for forms which have repetitive formatting for each field.
Several API improvements: A new setFormWidget() allows the definition of the form widget for editing a field which is a more useful alternative compared to reimplement createFormWidget(). It also allows the optional definition of an interface to update the view/model values, which avoids the need for specializing updateViewField() and updateModelField() these latter two functions have been deprecated in favour of two new functions updateViewValue() and updateModelValue() which only update the value but not other aspects such as visibility, validation state, or messages.

C) Non-backwards compatible changes

While in previous version of JWt, this class was only a data class that held the information related to an item, in 3.3.0 we modified this so that this class represents the widget itself. If you were redefining protected methods to customize the widget (i.e. createItemWidget() and updateItemWidget()), then this will no longer work as expected. The new system should be easier to customize (since you can simply specialize WMenuItem itself). In addition, we've simplified the rendering of a menu item so that a redundant layer of spans (or div's) has been removed. It makes the menu more consistent with the way CSS designers expect a menu to rendered, and this was done (you can guess the theme of this release by now ?) to be compatible with bootstrap's CSS styles.
The markup for this class has changed, and thus customized CSS will need to be updated.
The popup menu item class has been merged with WMenuItem (and WPopupMenu is now a specialized WMenu). This should not have noticable API changes, except for the changes in markup and CSS documented above.
WTreeNode, WTreeTable WTreeView
The markup for tree rendering has been changed (to using nested unordered list instead of nested tables), and thus customized CSS will need to be updated. The only API consequence is that WTreeNode.getLabelArea() is no longer returning a WTableCell but instead a WContainerWidget.

Release 3.2.3 (November 1, 2012)

This release contains mostly bug fixes and one new feature: a payment processing API.

A) New classes:

Render library: a library for rendering XHTML to (e.g.) PDF.

This library contains an XHTML parser and layout engine. It's main purpose is simplifying PDF report generation. The library uses PDFJet for low-level PDF functions. The layout engine does not understand all HTML/CSS concepts, but it does a decent job in static layout (blocks, inline elements, tables and floats) in any arbitrary combination, multi-page rendering, and accurate use of font metrics.

B) Main improvements:

Layout improvements
If you had massive trouble migrating to 3.2.2 because of the layout rewrite, then you'll appreciate the efforts we've made to make the layout algorithms in 3.2.3 much more robust and consistent.

Release 3.2.2 (July 23, 2012)

This release contains next to the usual bug fixes, the addition of new functionality for authentication.

A) Main improvements:

WBoxLayout, WGridLayout

The layout managers have been reimplement, to address various issues with the old implementation, including API (in particular the wonked side-effects of AlignTop, AlignJustify) inconsistencies and bugs.

The new implementation no longer uses tables when JavaScript is available, but instead using JavaScript-based layout with absolute positioning. The table-based implementation is still kept for plain HTML sessions (and progressive bootstrap). The code now uses exactly the same layout logic for both horizontal and vertical layout (but giving precedence to horizontal layout) and should be much more consistent (and perhaps also more performant). However, because of the many complexities and problems with the old code (inconsistent behaviour), you may see issues while upgrading. Please see the "Non-backwards compatible changes" below for hints on how to deal with this.


A drag & drop mime-type can now be specified on a per-item basis using a new ItemDataRole, and the mime-type for the entire selection is computed from these individual mime-types.


A new method setMouseOverDelay() allows to specify a delay for generating the mouseWentOver() event.


A new method deleteUser() was added, which deletes a user and all related authentication information.


A new method setAxisPadding() was added, which configures the amount of adding between the chart area and the axes.


A new method setCustomMarker() was added which allows the use of a user-defined path for the markers. A new role MarkserScaleFactorRole was added which allows overriding the marker size based on item model data.

B) Non-backwards compatible changes

WBoxLayout, WGridLayout
While migrating old code to this version, here are some tips:
  1. Alignment flags

    Previously, specifying an alignment for a widget in a layout, or for the layout when set to a container, had a double meaning. Not only would it implement the given alignment but also revert to passively letting HTML layout decide the layout of the contents, and adjust the parent (layout respectively container) accordingly. This had all kinds of side effects such as not propagating the size of layout-size-aware widgets and quirks in the vertical alignment.

    WContainerWidget.setLayout(layout, alignment) has been deprecated and will be removed from a future release. This call was almost always used to let the parent container resize to fit the size of the contained children, instead of fitting children in the parent container. This behaviour is now automatically deduced based on an (empty) size of the parent container. In case this heuristic does not work, then setting a non-0 maximum size on the container using setMaximumSize() will act as a trigger, with the added benefit that the parent will only be allowed to resize up to a specified maximum size.

    An alignment specified in W(Box/Grid)Layout::addWidget(widget, stretch, alignment) now purely affects the alignment but has no other side effects. The perferred and minimum sizes of a child widget or layout is now always taken into account.

  2. Child item sizes

    The layout algorithm is now implemented entirely in JavaScript, and is more gentle when dealing with a combination of cells (or columns/rows) that have a stretch factor and others that don't. Previously, a minimum (or fixed) size would be used to layout items that do not have a stretch factor. This had for example as a consequence that a WText would be narrowed down to its minimum width by using word wrapping throughout. Now, the preferred size is used for a child item, and shrinking to a minimum size only if necessary.

  3. Progressive bootstrap

    A layout in the first page of an application rendered using progressive bootstrap will no longer fully upgrade to a full JavaScript version, but will result in a hybrid (between table-based and JavaScript-based). If it doesn't work out as you'ld expect, then you should reconsider the use of progressive bootstrap, or the use of a layout manager in your first page.

Release 3.2.1 (March 30, 2012)

This release contains next to the usual bug fixes, the addition of new functionality for authentication.

A) New classes:

This namespace contains model and view classes for authentication. It implements password authentication using best practices, email verifiation, remember-me tokens, and provisions support for federated login with an implementation of OAuth 2.0 for authentication using third party identity providers.
This package has been isolated in a separate jar (jwt-auth.jar) because it has several third-party dependencies (see below).
A model class for forms. These models are used in Wt::Auth as the basis for RegistrationModel and AuthModel, and allow a more straight-forward customization of the underlying behavior of these forms.
A proxy model class which allows to share a source model read-only between multiple sessions.
A WTemplate-based standard view implementation that works in conjunction with WFormModel.
This class contains a number of utility functions that we found useful in projects using JWt, and were used internally in JWt already. They relate mostly to lower-level encoding and decoding functions: base64-, hex-, html-, and url-encoding/decoding.

B) Main improvements:

DateScale and DateTimeScale axes have improved auto-configuration of limits and timesteps, now taking into account the resolution.

C) Build/dependencies

The auth package has been isolated in a separate jar file because it has different dependencies.
Skip navigation links