Qt QML Hot Tips #3

Part 3 - Are your properties required?

if(someObjectProperty !== null) someObjectProperty.callFunction() is found littered throughout QML there are more things we could do to make that statement a bit nicer using nullish coalescing (Qt 5.15) and optional chaining (Qt 6.0). But we still encounter the fundamental problem: we kind of really expect someObjectProperty to be something really and the null case is really not nice but since our 10% code 90% error handler mindset is entrenched, there it is and people got used to it.

So be something!

From Qt 5.15 onwards we now have a nice shiny new keyword we can decorate our properties with: required

You can add required properties to your own components e.g.

// MyType.qml

Control {
   // the value property must be set if MyType is declared anywhere
   required property int value
}

// usage elsewhere:

MyType {
   // if not set with binding or assignment, an error is generated
   value: 10 
}        

Or you can make an existing property on an existing type required e.g.

// MyText.qml

Text {
   // make the existing property text "required"
   required property text
}

// usage elsewhere:

MyText {
   text: "must be set" // else error!
}         

Note: You can't assign an initial value to a required property from QML, as that would go directly against the intended usage of required properties. Note also that readonly required properties are also counter productive for what should be obvious reasons.

Your presence is required...

A "required" property will produce a compile time error if a delegate (or any QML component) does not elsewhere explicitly initialise or bind to it.

Consider this like a compiler complaining you did not pass in the required additional parameters for a re-implemented c++ constructor - the same can now go for QML and is part of the concept of treating your QML as a proper "class" - which is coming soon to a type compiler near you...

Use Required Properties:

• for when a property must be set from the outside in order that the QML component works correctly.

• to verify that a property you rely on being set, does actually get set (no need for those dodgy if(null) checks - the compiler does it for you!

• if a property uses the new "required" keyword, the QQmlEngine uses that instead of the context for resolving values, otherwise complain about unqualified lookups)

• Important for passing around information without relying on unqualified access (that's another topic for another day)

• for delegate types in Views properties i.e. to declare what properties are expected to be set on the delegate e.g. ListView (highly recommended). This ensures that the View delegate or component always gets the properties defined that it literally requires.

Using required properties allows the component to be moved into new contexts or parent without fear of only knowing if it will work at run-time as the compiler will tell you if the new context or parent doesn't set those properties. You've never moved a QML file right and it just worked? Yeah. I thought so. This way will at least (helpfully) tell you your effort to refactor was woefully inadequate and you need to think about it a bit more carefully.

I'm trying really hard not to get into object ids right now as I'll be writing about that another time, but yes, they are very important and there are seldom (but notable) times when not to set one.

There's a bit more info in the following blog post and documentation.