Guidelines

Using Qt in Sandbox comes with a few guidelines and restrictions

• Do not include Qt in places that don't need it, separate code using our UI Programming Patterns.
• Lambdas, bind and functional approach is a godsend to UI programming, use it!.
• Use Qt5 c++11 syntax for connect:
  • Bad: connect ( sender, SIGNAL(valueChanged(QString,QString)), receiver, SLOT(updateValue(QString)) ).
  • Good: connect ( sender, &Sender::valueChanged, receiver, &Receiver::updateValue).
  • Good: connect ( sender, &Sender::valueChanged, [](){ /*lambda*/ } ).
• Do not use UI files (Qt Creator)
  • The generated code is often more complex than if you had written it by yourself. Writing Qt layouts is not hard, quite the contrary.
  • It obfuscates for debugging. Now you have to look in several places including generated code to understand how the final result is produced.
  • By using UI files you are effectively avoiding learning how to program Qt Widgets. It's better for everyone involved if you learn and get comfortable with it.
• All UI Strings must be available for localization (using QObject::tr method or QT_TR_NOOP macro).
• Use CrySignal to implement observable structures that should not depend on Qt.
• Always make sure that you are not duplicating functionality that otherwise exists in the framework.
• Expose generic functionality in EditorCommon and try to reuse as much as is possible. A lot of reusable components are already there, please add more if necessary.
• Use our replacement classes for some Qt classes (see below).
• Use ItemModels effectively: ItemModels and ItemViews.
• Only QWidgets and QGraphicsViews are allowed. QtQuick or other parts of Qt are not available.

Reusable classes

The Sandbox code contains a large library of reusable components, such as Qt Widgets, various helpers, and platform abstraction tools. All of these extensions can be found in the EditorCommon project, in particular, EditorCommon/Controls and EditorCommon/Dialogs.

The goal is to provide a more powerful framework and a unified way to solve UI problems across the whole tool. By using these you will get a better UI, a faster result, and help the Sandbox look and feel consistent. Feel free to call and extend this framework as much as possible.

Must Use

You should always use the following classes instead of the original ones. Failure to do this should be caught during code review. Only by using the right set of classes everywhere can we ensure consistency throughout the Sandbox.

Recommended use

It is recommended to use the following classes instead of the original ones.

Other reusable UI components

All the reusable widgets and Qt helpers are available in the EditorCommon package. Take a look at the source code to discover more useful classes!

Another set of extensions to Qt is the ItemModel Framework which is described in a dedicated page.