qooxdoo Documentation Release 2.1
qooxdoo developers
November 14, 2012
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...... 4 1.2.8 Migration...... 4 1.3 Architectural Overview...... 4 1.4 Getting Started...... 5 1.4.1 qx.Website...... 5 1.4.2 qx.Desktop...... 6 1.4.3 qx.Mobile...... 7 1.4.4 qx.Server...... 9 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...... 52 2.4.1 Data Binding...... 52
i 3 qx.Website 65 3.1 General...... 65 3.1.1 qx.Website Overview...... 65 3.2 Tutorials...... 69 3.2.1 Tutorial: Building Notifications...... 69 3.3 Technical Topics...... 72 3.3.1 Plugins...... 72 3.3.2 Referring to the qx.bom API...... 73
4 qx.Desktop 81 4.1 Overview...... 81 4.1.1 Widgets...... 81 4.1.2 Composites...... 81 4.1.3 Roots...... 82 4.1.4 Applications...... 82 4.1.5 Communication...... 83 4.2 Widgets Introduction...... 83 4.2.1 Widget...... 83 4.2.2 Basic Widgets...... 84 4.2.3 Interaction...... 86 4.2.4 Resources...... 89 4.2.5 Selection Handling...... 91 4.2.6 Drag & Drop...... 94 4.2.7 Inline Widgets...... 98 4.2.8 Custom Widgets...... 101 4.2.9 Form Handling...... 104 4.2.10 Menu Handling...... 120 4.2.11 Window Management...... 124 4.2.12 HTML Editing...... 125 4.2.13 Table Styling...... 141 4.2.14 Widget Reference...... 154 4.3 Layouts...... 154 4.3.1 Layouting...... 154 4.4 Themes...... 159 4.4.1 Theming...... 159 4.4.2 Appearance...... 165 4.4.3 Custom Themes...... 171 4.4.4 Decorators...... 173 4.4.5 Web Fonts...... 176 4.4.6 Using themes of contributions in your application...... 178 4.4.7 Three steps for efficient theme development...... 179 4.5 Technical Concepts...... 182 4.5.1 The Event Layer...... 182 4.5.2 HTML Element Handling...... 183 4.5.3 The Focus Layer...... 185 4.5.4 Using qx.Website in qx.Desktop...... 187 4.6 Tutorials...... 188 4.6.1 Tutorial Part 1: The Beginning of a Tweets App...... 188 4.6.2 Tutorial Part 2: Finishing the UI...... 191 4.6.3 Tutorial Part 3: Time for Communication...... 195 4.6.4 Tutorial Part 4.1: Form Handling...... 199 4.6.5 Tutorial Part 4.2: Custom Widgets...... 202 4.6.6 Tutorial Part 4.2.1: Basic Theming...... 209 4.6.7 Tutorial Part 4.3: Translation...... 212 ii 4.6.8 Tutorial Part 4.4: Unit Testing...... 216 4.6.9 Tutorial Part 4.4.1: Automated UI Testing...... 221 4.6.10 Tutorial Part 4.5: Virtual List...... 227
5 qx.Mobile 231 5.1 General...... 231 5.1.1 Overview...... 231 5.1.2 qx.Mobile Requirements...... 233 5.1.3 Getting Started with qooxdoo qx.Mobile...... 234 5.2 Tutorials...... 235 5.2.1 Tutorial: Creating a Tweets Client with qooxdoo mobile...... 235 5.3 Development...... 244 5.3.1 Mobile and tablet switch...... 244 5.3.2 Theming...... 248 5.3.3 Debugging...... 250 5.4 Deployment...... 252 5.4.1 Deployment...... 252
6 qx.Server 253 6.1 Server Overview...... 253 6.1.1 Included Features...... 253 6.1.2 Supported Runtimes...... 253 6.1.3 Installation...... 254 6.1.4 Basic Example...... 254 6.1.5 Additional Scenarios...... 254 6.2 qx.Server Requirements...... 254 6.2.1 Runtimes...... 255 6.2.2 Installation...... 255 6.3 RequireJS Support...... 255 6.3.1 Representable interface...... 256 6.3.2 Config file...... 256
7 Communication 259 7.1 Low-level requests...... 259 7.2 Higher-level requests...... 259 7.2.1 Higher-level requests...... 259 7.2.2 AJAX...... 264 7.3 REST...... 266 7.3.1 REST (Representational State Transfer)...... 266 7.4 Remote Procedure Calls (RPC)...... 269 7.4.1 RPC (Remote Procedure Call)...... 269 7.4.2 RPC Servers...... 275 7.5 Specific Widget Communication...... 279 7.5.1 Using the remote table model...... 279
8 Development 283 8.1 Application Creation...... 283 8.1.1 Application Skeletons...... 283 8.2 Debugging...... 286 8.2.1 Logging System...... 286 8.2.2 Debugging Applications...... 288 8.3 Performance...... 290 8.3.1 Memory Management...... 290 8.3.2 Profiling Applications...... 293 8.4 Testing...... 294
iii 8.4.1 Unit Testing...... 294 8.4.2 Test Runner...... 294 8.4.3 Simulator...... 304 8.4.4 Simulator: Locating elements...... 309 8.5 Code Organisation...... 311 8.5.1 Custom Libraries...... 311 8.6 Parts...... 313 8.6.1 Parts and Packages Overview...... 313 8.6.2 Using Parts...... 314 8.6.3 Further Resources...... 318 8.7 Internationalization...... 318 8.7.1 Internationalization...... 318 8.8 Documenting Code...... 322 8.8.1 Writing API Documentation...... 322 8.8.2 JSDoc Reference...... 324 8.9 Miscellaneous...... 336 8.9.1 Image clipping and combining...... 336 8.9.2 Reporting Bugs...... 339 8.9.3 An Aspect Template Class...... 339 8.9.4 Internet Explorer specific settings...... 341
9 Standard Applications 343 9.1 Demo Applications...... 343 9.1.1 Demobrowser...... 343 9.1.2 Feedreader...... 344 9.1.3 Playground...... 344 9.1.4 ToDo...... 345 9.1.5 Tutorial...... 346 9.1.6 Showcase...... 346 9.1.7 Widgetbrowser...... 347 9.2 Developer Tools...... 347 9.2.1 API Viewer...... 347 9.2.2 Testrunner...... 349 9.2.3 Inspector...... 349 9.2.4 Simulator...... 356 9.2.5 Feature Configuration Editor...... 361
10 Tooling 365 10.1 Introduction...... 365 10.1.1 Introduction to the SDK...... 365 10.1.2 SDK Requirements...... 366 10.1.3 Hello World...... 368 10.1.4 SDK Structure...... 373 10.1.5 Application Structure...... 374 10.1.6 Manifest.json...... 376 10.1.7 Code Structure...... 377 10.2 Generator...... 379 10.2.1 Generator Overview...... 379 10.2.2 Generator Usage...... 381 10.2.3 Generator Configuration File...... 383 10.2.4 Generator Script Optimizations...... 387 10.2.5 Generator Configuration Articles...... 391 10.2.6 Generator Configuration Background Information...... 406 10.2.7 Tutorials...... 412
iv 10.2.8 References...... 419 10.3 Lint...... 419 10.3.1 Tutorials...... 419 10.4 Application Wizard...... 420 10.4.1 Create Application...... 420 10.5 Migration...... 422 10.5.1 Migration Guide...... 422 10.6 Other Tools...... 423
11 References 425 11.1 Core...... 425 11.1.1 Class Declaration Quick Ref...... 425 11.1.2 Interfaces Quick Ref...... 426 11.1.3 Mixin Quick Ref...... 427 11.1.4 Properties Quick Reference...... 428 11.1.5 Array Reference...... 429 11.1.6 Framework Generator Jobs...... 430 11.2 GUI Toolkit...... 431 11.2.1 Widget Reference...... 431 11.2.2 Layout Reference...... 476 11.3 Tooling...... 487 11.3.1 Generator Default Jobs...... 487 11.3.2 Generator Config Keys...... 494 11.3.3 Generator Config Macros...... 515 11.3.4 Syntax Diagrams...... 517 11.3.5 The Format of PO Files...... 517 11.4 Miscellaneous...... 519 11.4.1 Third-party Components...... 519 11.5 Glossary...... 520 11.5.1 Glossary...... 520 11.6 License...... 522 11.6.1 qooxdoo License...... 522
Index 537
v 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 2.1 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) – 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 2.1
• 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 • Integrated functional testing framework Simulator
1.2. Feature Overview 3 qooxdoo Documentation, Release 2.1
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.) • 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 inlcude 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.
4 Chapter 1. Introduction qooxdoo Documentation, Release 2.1
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 as a single .js file, 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. It does not include any UI widgets. It is suitable if you basically want to manipulate DOM elements on a page. 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 6+ Firefox 2+ Opera 9+ Safari 3+ Chrome 2+
1.4. Getting Started 5 qooxdoo Documentation, Release 2.1
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