qooxdoo Documentation Release 5.0.2
qooxdoo developers
January 12, 2017
Copyright ©2011–2017 1&1 Internet AG
CONTENTS
1 Introduction 1 1.1 About...... 1 1.1.1 Framework...... 1 1.1.2 GUI Toolkit...... 1 1.1.3 Communication...... 1 1.1.4 More Information (online)...... 2 1.2 Feature Overview...... 2 1.2.1 Runtimes...... 2 1.2.2 Object-orientation...... 2 1.2.3 Programming...... 2 1.2.4 Internationalization...... 3 1.2.5 API reference...... 3 1.2.6 Testing...... 3 1.2.7 Deployment...... 3 1.2.8 Migration...... 4 1.3 Architectural Overview...... 4 1.4 Getting Started...... 4 1.4.1 qx.Website...... 4 1.4.2 qx.Desktop...... 6 1.4.3 qx.Mobile...... 7 1.4.4 qx.Server...... 8 1.4.5 Others...... 10
2 Core 11 2.1 Object Orientation...... 11 2.1.1 Introduction to Object Orientation...... 11 2.1.2 Features of Object Orientation...... 12 2.1.3 Classes...... 18 2.1.4 Interfaces...... 24 2.1.5 Mixins...... 27 2.2 Properties...... 29 2.2.1 Introduction to Properties...... 29 2.2.2 Properties in more detail...... 33 2.2.3 Initialization Behavior...... 43 2.2.4 Property features summarized...... 44 2.3 Environment...... 46 2.3.1 Environment...... 46 2.4 Data Binding...... 51 2.4.1 Data Binding...... 51
i 2.5 Interaction Events...... 64 2.5.1 Pointer Events...... 64 2.5.2 Gesture Events...... 64
3 qx.Website 67 3.1 General...... 67 3.1.1 qx.Website Overview...... 67 3.1.2 Module Overview...... 68 3.2 Widget Library...... 74 3.2.1 qx.Website Widgets...... 74 3.3 Tutorials...... 76 3.3.1 Tutorial: Building Notifications...... 76 3.4 Layouts...... 80 3.4.1 Layouts...... 80 3.5 Technical Topics...... 81 3.5.1 Plugins...... 81 3.5.2 Referring to the qx.bom API...... 82
4 qx.Desktop 89 4.1 Overview...... 89 4.1.1 Widgets...... 89 4.1.2 Composites...... 89 4.1.3 Roots...... 90 4.1.4 Applications...... 90 4.1.5 Communication...... 91 4.2 How to Develop a qx.Desktop Application...... 91 4.2.1 General Cycle of Activities...... 91 4.2.2 Build Version...... 91 4.2.3 Running the Source Version through a Web Server...... 92 4.3 Widgets Introduction...... 93 4.3.1 Widget...... 93 4.3.2 Basic Widgets...... 94 4.3.3 Interaction...... 96 4.3.4 Resources...... 99 4.3.5 Selection Handling...... 102 4.3.6 Drag & Drop...... 105 4.3.7 Inline Widgets...... 109 4.3.8 Custom Widgets...... 111 4.3.9 Form Handling...... 116 4.3.10 Menu Handling...... 132 4.3.11 Window Management...... 136 4.3.12 Table Styling...... 137 4.3.13 Widget Reference...... 151 4.4 Layouts...... 151 4.4.1 Layouting...... 151 4.5 Themes...... 156 4.5.1 Theming...... 156 4.5.2 Appearance...... 164 4.5.3 Custom Themes...... 170 4.5.4 Decorators...... 172 4.5.5 Web Fonts...... 174 4.5.6 Using themes of contributions in your application...... 175 4.5.7 Three steps for efficient theme development...... 177 4.6 Technical Concepts...... 179 ii 4.6.1 The Event Layer...... 179 4.6.2 HTML Element Handling...... 180 4.6.3 The Focus Layer...... 182 4.6.4 Using qx.Website in qx.Desktop...... 184 4.7 Tutorials...... 185 4.7.1 Tutorial Part 1: The Beginning of a Tweets App...... 185 4.7.2 Tutorial Part 2: Finishing the UI...... 187 4.7.3 Tutorial Part 3: Time for Communication...... 191 4.7.4 Tutorial Part 4.1: Form Handling...... 196 4.7.5 Tutorial Part 4.2: Custom Widgets...... 198 4.7.6 Tutorial Part 4.2.1: Basic Theming...... 204 4.7.7 Tutorial Part 4.3: Translation...... 208 4.7.8 Tutorial Part 4.4: Unit Testing...... 212 4.7.9 Tutorial Part 4.5: Virtual List...... 217 4.8 Migration...... 220 4.8.1 Migration from qx.Desktop 2.x...... 220
5 qx.Mobile 223 5.1 General...... 223 5.1.1 Overview...... 223 5.1.2 qx.Mobile Requirements...... 225 5.1.3 Getting Started with qooxdoo qx.Mobile...... 226 5.2 Tutorials...... 227 5.2.1 Tutorial: Creating a Tweets Client with qooxdoo mobile...... 227 5.3 Development...... 236 5.3.1 Mobile and tablet switch...... 236 5.3.2 Theming...... 240 5.3.3 Migrating a qx.Mobile theme to another version...... 244 5.3.4 Resolution and Pixel Density...... 249 5.3.5 Debugging...... 252 5.4 Deployment...... 254 5.4.1 Deployment...... 254
6 qx.Server 255 6.1 Server Overview...... 255 6.1.1 Included Features...... 255 6.1.2 Supported Runtimes...... 255 6.1.3 Installation...... 256 6.1.4 Basic Example...... 256 6.1.5 Additional Scenarios...... 256 6.2 qx.Server Requirements...... 256 6.2.1 Runtimes...... 257 6.2.2 Installation...... 257 6.3 RequireJS Support...... 257 6.3.1 Representable interface...... 258 6.3.2 Config file...... 258
7 Communication 261 7.1 Low-level requests...... 261 7.2 Higher-level requests...... 261 7.2.1 Higher-level requests...... 261 7.2.2 AJAX...... 266 7.3 REST...... 268 7.3.1 REST (Representational State Transfer)...... 268
iii 7.4 Remote Procedure Calls (RPC)...... 272 7.4.1 RPC (Remote Procedure Call)...... 272 7.4.2 RPC Servers...... 277 7.5 Specific Widget Communication...... 281 7.5.1 Using the remote table model...... 281 7.6 Development & Testing...... 284 7.6.1 FakeServer...... 284
8 Development 287 8.1 Application Creation...... 287 8.1.1 Application Skeletons...... 287 8.1.2 How to Develop a qooxdoo Application...... 290 8.2 Debugging...... 291 8.2.1 Logging System...... 291 8.2.2 Debugging Applications...... 292 8.3 Performance...... 295 8.3.1 Memory Management...... 295 8.3.2 Profiling Applications...... 297 8.4 Testing...... 298 8.4.1 Unit Testing...... 298 8.4.2 Test Runner...... 299 8.5 Code Organisation...... 309 8.5.1 Code Organisation Introduction...... 309 8.5.2 Custom Libraries...... 310 8.5.3 qooxdoo-contrib...... 312 8.6 Parts...... 314 8.6.1 Parts and Packages Overview...... 314 8.6.2 Using Parts...... 315 8.6.3 Further Resources...... 319 8.7 Internationalization...... 320 8.7.1 Internationalization...... 320 8.8 Documenting Code...... 323 8.8.1 Writing API Documentation...... 323 8.8.2 JSDoc Reference...... 326 8.8.3 @ignore...... 342 8.9 Miscellaneous...... 343 8.9.1 Image clipping and combining...... 343 8.9.2 Reporting Bugs...... 346 8.9.3 An Aspect Template Class...... 346 8.9.4 Internet Explorer specific settings...... 348
9 Standard Applications 351 9.1 Demo Applications...... 351 9.1.1 Demobrowser...... 351 9.1.2 Feedreader...... 352 9.1.3 Playground...... 352 9.1.4 ToDo...... 353 9.1.5 Tutorial...... 354 9.1.6 Showcase...... 354 9.1.7 Widgetbrowser...... 355 9.2 Developer Tools...... 355 9.2.1 API Viewer...... 355 9.2.2 Testrunner...... 357
iv 10 Tooling 359 10.1 Introduction...... 359 10.1.1 Introduction to the SDK...... 359 10.1.2 SDK Requirements...... 360 10.1.3 Hello World...... 363 10.1.4 SDK Structure...... 367 10.1.5 Application Structure...... 368 10.1.6 Manifest.json...... 370 10.1.7 Code Structure...... 371 10.2 Generator...... 372 10.2.1 Generator Overview...... 372 10.2.2 Generator Features...... 374 10.2.3 Generator Usage...... 378 10.2.4 Generator Script Optimizations...... 380 10.2.5 Adding Dependency Information Manually...... 384 10.2.6 Configuration...... 385 10.2.7 Tutorials...... 415 10.2.8 References...... 419 10.3 Grunt...... 419 10.3.1 Grunt frontend...... 419 10.4 Lint...... 423 10.4.1 Tutorials...... 423 10.5 Application Wizard...... 424 10.5.1 Create Application...... 424 10.6 Migration...... 425 10.6.1 Migration Guide...... 425 10.7 Other Tools...... 427
11 References 429 11.1 Core...... 429 11.1.1 Class Declaration Quick Ref...... 429 11.1.2 Interfaces Quick Ref...... 430 11.1.3 Mixin Quick Ref...... 431 11.1.4 Properties Quick Reference...... 432 11.1.5 Array Reference...... 433 11.1.6 Framework Generator Jobs...... 434 11.2 GUI Toolkit...... 435 11.2.1 Widget Reference...... 435 11.2.2 Layout Reference...... 479 11.3 Tooling...... 490 11.3.1 Default Action Jobs...... 490 11.3.2 Default Includer Jobs...... 497 11.3.3 Generator Config Keys...... 498 11.3.4 Generator Config Macros...... 523 11.3.5 qooxdoo Generator Cheat Sheet - v.5.0.2...... 525 11.3.6 Syntax Diagrams...... 534 11.3.7 The Format of PO Files...... 535 11.4 Miscellaneous...... 536 11.4.1 Third-party Components...... 536 11.5 Glossary...... 538 11.5.1 Glossary...... 538 11.6 License...... 540 11.6.1 qooxdoo License...... 540
v Index 555
vi CHAPTER ONE
INTRODUCTION
1.1 About qooxdoo (pronounced [’kuksdu:]) is a universal JavaScript framework that enables you to create applications for a wide range of platforms. With its object-oriented programming model you build rich, interactive applications (RIAs), native-like apps for mobile devices, traditional web applications or even applications to run outside the browser. You leverage its integrated tool chain to develop and deploy applications of any scale, while taking advantage of a comprehensive feature set and a state-of-the-art GUI toolkit. qooxdoo is open source under liberal licenses, run by one of the world’s leading web hosts 1&1, with a vibrant community.
1.1.1 Framework
The core of qooxdoo is entirely class-based and tries to leverage the features of object-oriented JavaScript. It is largely based on namespaces to allow for easy integration with other libraries and existing user code. Most modern browsers are supported (e.g. Firefox, Internet Explorer, Opera, Safari, Chrome). It comes with a comprehensive API reference that is auto-generated from Javadoc-like comments. The fast and complete JavaScript parser not only allows documentation generation but is an integral part of the automatic build process that makes optimizing, compressing, linking and deployment of custom applications very user-friendly. Internationalization and localization of applications for various countries and languages is a core feature and easy to use. More ...
1.1.2 GUI Toolkit
Despite being a pure JavaScript framework, qooxdoo is quite on par with GUI toolkits like Qt or SWT when it comes to advanced yet easy to implement user interfaces. It offers a full-blown set of widgets that are hardly distinguishable from elements of native desktop applications. Full built-in support for keyboard navigation, focus and tab handling and drag & drop is provided. Dimensions can be specified as static, auto-sizing, stretching, percentage, weighted flex or min/max, or even as combinations of those. All widgets are based on powerful and flexible layout managers which are a key to many of the advanced layout capabilities. Interface description is done programmatically in JavaScript for maximum performance. No HTML has to be used and augmented to define the interface. The qooxdoo developer does not even have to know CSS to style the interface. Clean and easy-to-configure themes for appearance, colors, borders, fonts and icons allow for a full-fledged styling.
1.1.3 Communication
While being a client-side and server-agnostic solution, the qooxdoo project includes different communication facilities, and supports low-level XMLHttpRequests (XHR) as well as an RPC API. An abstract transport layer supports queues,
1 qooxdoo Documentation, Release 5.0.2 timeouts and implementations via XHR, Iframes and Scripts. Like the rest of qooxdoo it fully supports event-based programming which greatly simplifies asynchronous communication.
1.1.4 More Information (online)
There is more information available about the project on the project’s home page.
1.2 Feature Overview
A typical qooxdoo application is created by leveraging the integrated development tools and the client-side program- ming model based on object-oriented JavaScript. Developers can fully concentrate on creating application without worrying about low-level cross-browser issues.
1.2.1 Runtimes
• qooxdoo supports a wide range of JavaScript environments: – desktop browsers (Internet Explorer, Firefox, Opera, Safari, Chrome) – mobile browsers (iOS, Android, Windows Phone) – browserless JS engines (node.js, Rhino, ...) • No plugins required (neither ActiveX, Java, Flash nor Silverlight needed) • Non-critical modifications of the native JavaScript objects to allow for easy integration with other libraries and custom code
1.2.2 Object-orientation
• Framework is fully based on classes • Minimal pollution by global variables due to namespacing • Besides regular classes, it offers abstract, static or singleton classes • Constructors and destructors • Public, protected and private members by naming convention, that can (partly) be enforced during development • Single inheritance, full polymorphism • Java-like interfaces • Ruby-esque mixins • So-called dynamic properties, a very convenient and powerful way to have optimized setter and getter methods generated from simple configuration
1.2.3 Programming
• Pure JavaScript • No HTML knowledge required • No CSS knowledge required
2 Chapter 1. Introduction qooxdoo Documentation, Release 5.0.2
• No DOM knowledge required • Complete support for event-based programming • Development of qooxdoo applications fully supported on all platforms, e.g. Windows, Linux, all Unixes, Mac OS X • Skeletons as pre-configured basis for full-featured custom applications • Many sample applications and examples • Designed for high performance • Aid in developing memory-leak free user applications • Extensive logging capabilities (e.g. different log appenders, Firebug support) • Straightforward debugging (e.g. object introspection, benchmarking) • Browser history management, i.e. browser back/forward button, bookmarks • Cookies • Generic JavaScript pretty printer / code formatter for unified code style • Alternative development platforms offered by third parties
1.2.4 Internationalization
• Built-in internationalization (i18n) and localization (l10n) support • Supporting all languages and locales, at least of this planet • Based on the comprehensive Unicode Common Locale Data Repository (CLDR) • Well-known translation file format (.po) • Support by professional, free translation tools (“po editors”) on all platforms
1.2.5 API reference
• Extended Javadoc-like source code comments • Full API reference for both framework and custom application • Online and offline API viewer application • Search functionality
1.2.6 Testing
• Integrated unit testing framework Test Runner
1.2.7 Deployment
• Generation of a self-contained and easily deployable “build” version • Complexity of the build process hidden behind user-friendly commands • JavaScript compression (removal of whitespaces, etc.)
1.2. Feature Overview 3 qooxdoo Documentation, Release 5.0.2
• Automatic dependency resolution of JavaScript classes; no need for manual “require” statements or tweaking a custom build • Automatic linking of JavaScript classes (“JS linker”) • Copying of required static resources like images or other external files into a self-contained build • String extraction • Shortening and obfuscating local variables and/or private members • Optional browser-specific variant generation for selected feature sets (e.g. Firefox-only build) • Generation of build versions depending on user-defined variants, which allows for different products from the same code base • Removal of debug statements within the application code before deployment
1.2.8 Migration
• Support for easy migration of custom applications from one framework release to another • As painless as technically feasible • Fully integrated into the regular build system • All non-ambiguous changes are done automatically for maximum convenience and to avoid manual find/replace errors • All ambiguous or semantic changes that require some developer decision are put into a comprehensive checklist
1.3 Architectural Overview
The following diagram tries to show the main aspects of qooxdoo and how they are organized in general. Please keep in mind that this diagram does not include all features of qooxdoo. You can see the four main areas for which qooxdoo can be used and what layers are useful in that dedicated scenario.
1.4 Getting Started
This section provides you with resources that help you pick the qooxdoo package for your needs, set it up on your local machine and get started with writing your own code.
1.4.1 qx.Website
qx.Website is a low-level package that you deploy by including one or more .js file(s) in your HTML pages, like you would with many other JavaScript libraries. Its contents encompasses DOM and BOM abstractions, cross-browser event handling, a selector engine, and a stripped-down version of the qooxdoo class system. A small set of UI widgets
4 Chapter 1. Introduction qooxdoo Documentation, Release 5.0.2 is available. qx.Website is suitable if you basically want to manipulate DOM elements and styles on a page, as opposed to creating a single-page application written entirely in JavaScript. qx.Website Requirements
Here are the requirements for developing and deploying with qooxdoo qx.Website. You will usually include the qx.Website library on an HTML page and then write code that utilizes its API.
Browsers
Code written against the qx.Website API will run in all major web browsers, particularly:
Internet Explorer 8+
Firefox 3.5+
Opera 15+
Safari 6+
Chrome qx.Website widgets are currently experimental and will not work in all browsers.
Installation and Setup
Download the qx.Website component from qooxdoo’s download page and place it in a suitable URI reachable from your development environment. Then include this URI with a