QML Object Properties
Each QML object type defines a series of properties. Each time an instance of the object type is created, these attributes of the instance are also automatically created. Next we discuss several different types of attributes.
id attribute
Each QML object type has a uniquely determined id attribute. This attribute is provided by the QML language itself, and cannot be redefined and overloaded in the QML object type.
We must specify a value for the id attribute to allow the object to be uniquely identified and available for reference by other objects. The Id attribute value must start with a lowercase letter or underscore, and can only contain letters, numbers, and underscores.
The following is a TextInput object and a Text object. The id property of the TextInput object is "myTextInput". The text property value of the Text object is set to the same as the text property value of the TextInput object through myTextInput.text.
We can later refer to the object through the id attribute in the visible domain of the component. Therefore, the id attribute value must be unique within the component's visible domain.
Once the object instance is created, the id attribute value cannot be changed. The Id attribute looks like an ordinary attribute, but it is not a real ordinary attribute. We apply special semantics to it, for example: in the above example, we cannot use myTextInput.id.
The property attribute
a property is a property of an object, can be assigned to the static value or dynamically bound to the expression. The value of a property can be read by other objects. In general, the property property can also be modified by other objects, unless the QML type explicitly specifies that the property property cannot be modified.
[Define property property]
A property property can be defined in C ++ and registered with the QML type system through Q_PROPERTY. Of course, we can also customize the property properties of the object in the QML document through the following syntax:
In this way, an object can expose some specific values to other objects, or it is easier to maintain some internal state.
The name of the property must start with a lowercase letter and can only contain letters, numbers, and underscores. JavaScript reserved keywords cannot be used as the name of the property attribute. The Default keyword is optional, and the details of the default and default property modifiers will be discussed later.
Defining a custom property property implicitly creates a value-change signal for the property property, which is associated with a signal handler named on <PropertyName> Changed. <PropertyName> is the name of the property, and the first letter should be capitalized.
For example: The following defines two property properties and implements its signalhandler:
[Legal type of custom property attribute]
The enumerated types in the QML basic types can be used as custom property attribute types. For example: The following are all legal property attribute declarations:
Some basic types provided by the QtQuick module cannot be used as property types unless the QtQuick module is imported in the QML document.
The basic type of var is a general type, which can save any type of value, including lists and objects:
In addition, any QML object type can be used as the property attribute type. E.g:
This is also applicable to custom QML types. If a QML type is defined in the ColorfulButton.qml file, the property property of the ColorfulButton type is also legal.
[Legal property value]
We can assign values to defined property attributes in two ways:
*initialization
* Assign
The value can be a static value or a binding expression.
{initialization}
Property property initialization:
We can also initialize the assignment when defining the property property:
Examples of initial assignment are as follows:
{Assignment}
We can use JavaScript code to assign values to the property attribute as follows:
Examples are as follows:
[Legal property value]
As mentioned before, we can assign two types of values to the property attribute: static values and binding expressions:
Examples:
In many cases, the value of the string type can be automatically converted to many different types of values, because QML provides the conversion of the string type to other types (this is why you can assign the "red" value to the color attribute).
Special attention must be paid that in the case of binding to an expression, the expression on the right must return the value of the Qt.binding () function, which returns the appropriate value type. An expression can be directly assigned when the property property is initialized, without the need to use that function (in fact, using the function will also cause errors).
【Type Safety】
Attributes are all type safe. The value assigned to the attribute must match the type.
For example, the following assignment will cause an error:
If the property is assigned the wrong value at runtime, the assignment will not succeed and an error will be generated.
As mentioned before, some attribute types do not have good types to express their values. At this time, the QML engine provides good string type conversion. For example: color attribute, the value type stored in this attribute should be color type instead of string type, but you can assign it a string type value without error.
[Special property attribute type]
Property property of object list type
The property property of the List type can also be assigned the value of the QML object type list. The form of assignment is as follows:
For example: Item type has a state attribute, which can be used to save a list of State object types. The following code is used to initialize the list:
If the list contains only one item, the square brackets can be omitted:
We can define the property properties of the object list type as follows:
List type property declaration examples are as follows:
If you want to declare a property for storing list values, but not necessarily for storing QML object type values, you need to declare the property property of var at this time.
[Grouped properties]
In some cases, we can divide attributes into sub-attribute groups according to logic. These sub-attributes can be assigned by "." Or group.
For example: Text type has a font group attribute. In the following, the first Text object uses "." To initialize the value of the font, and the second uses the group to assign the value:
Group attribute types are all basic types. Part of these basic types is provided by the QML language, and the other part is provided by the Qt Quick module.
【Attribute Alias】
An attribute alias is to save a reference to another attribute. Unlike the definition of common attributes, the definition of common attributes requires the allocation of a new, unique storage space, and an attribute alias is simply connected to the attribute.
Definition of attribute alias The root attribute definition is similar, except that the attribute alias needs to use the alias keyword instead of the property type in the attribute definition. The value on the right must be a legal reference alias:
Unlike ordinary attributes, an alias can only refer to an object or an attribute of an object.
For example: The following Button type has an alias of the buttonText property, which is linked to the text property of the child Text object:
The following code creates a Button and defines a text string:
Modify buttonText, directly modify the value of textItem.text, it will not modify other values. If buttonText is not an attribute alias, modifying its value will not modify the displayed text, because attribute binding is not bidirectional.
[Considering attribute aliases]
The property alias will be activated only after the component is fully initialized. If an uninitialized alias is referenced, an error will be generated. In addition, generating an attribute alias for an attribute alias will also cause an error:
We can create an attribute alias with the same name for an existing attribute, which will overwrite the existing attribute. For example: The following QML type has an alias for the color attribute, and the built-in Rectangle attribute Rectangle :: color attribute:
[Default attribute]
An object definition can contain a default attribute. If an object () child object is defined in another object (parent object) without assigning any attributes to the parent object, then the child object is the value of the default property of the parent object. The default keyword is required to be declared as the default attribute.
For example, the object in the following MyLabel.qml file has a default property of someText:
We can assign someText default properties in the MyLabel object definition:
The above two are equivalent to the following one:
However, because the someText property is marked as the default property, there is no need to explicitly assign the Text object to this default property.
You may also have noticed that sub-objects can be added to any Item-based type without explicitly adding them to sub-attributes. This is because the default attribute of the Item is the data attribute, and any objects added to the Item are automatically added to its list of child objects.
The default attributes are very useful for reassigning sub-objects. Take a look at the TabWidget example, which uses the default properties to automatically reassign TabWidget's child objects as its list of child objects.
[Read-only attribute]
The definition of any object can use the readonly keyword to define read-only attributes, using the following syntax:
The read-only attribute must specify a value during initialization. Once the read-only attribute is initialized, it can no longer be assigned, whether it is assignment (using "=") or other means.
For example, the following Component.onCompleted code block is illegal:
Note: A read-only attribute cannot be declared as a default attribute or an attribute alias.
【Attribute modification object】
Attributes can have attribute value modification objects associated with them. We can define attributes to modify the object instance as follows, and associate with specific attributes:
It should be noted that the above syntax is actually an object declaration that will instantiate an existing property of an object operation.
Specific attribute modification types can only be applied to specific attribute types, but this is not enforced by the language. For example: The NumberAnimation type provided by the QtQuick module only affects the properties of numeric types (such as int or real). If NumberAnimation is used for non-numeric properties, it will not cause an error, but non-numeric properties will not generate animation. Attribute modification type actions are closely related to the realization of specific attributes.
The Signal property
signal is a notification from the object type when certain events occur: for example, a property change, an animation starts or stops, or when an image download is complete. For example, the MouseArea type emits a click signal when the user clicks.
When a signal is emitted, the object can be notified via a signal handler. The definition syntax of a signalhandler is on <Signal>, <Signal> is the name of the signal, and the first letter should be capitalized. Signalhandler must be implemented within the definition of the object that emits the signal, and signalhandler must include a JavaScript code block, which will be executed when the signal handler is called.
For example, the definition of the MouseArea object can define a signal handler of type onClicked. When the MouseArea is clicked, the signal handler will be called, causing the console to print out the message:
[Define Signal Attribute]
We can use Q_SIGNAL to define Signal properties in C ++ classes and register them with the QML type system. Optionally, we can also use the following syntax to define the signal attribute in the QML document:
Defining two signals or methods with the same name in a type block will generate an error. However, we can use the existing signal type to define a new signal (this will make the previous signal invisible)
The following is an example of a signal definition:
If a signal has no parameters, then "()" is optional. If parameters are used, the type of the parameter must be specified, such as the string and val parameters in the actionPerformed signal above. The allowed parameter types are the same as defined in the property property described earlier.
To emit a signal, a method is called. Any signal handler associated with the signal will be executed when the signal is emitted, and the handlers can use the name of the defined signal parameters and obtain the expected parameters.
[Attribute change signal]
The QML type also provides built-in attribute change signals, which are emitted when the attribute value is changed. Next we will introduce the benefits of signals and how to use them.
[Signal Handler attribute]
Signal handlers are special method attribute types. When the signal is emitted, the specific method associated with the signal will be called. Adding a signal to QML will automatically add a signalhandler associated with it. By default, the function will be empty. The client can provide its own implementation to implement the program logic:
Consider the following SquareButton type, which is defined in the SquareButton.qml file and defines two signals: activated and deactived:
These signals can be obtained from any SquareButton object in other QML files in the same directory. The client also provides signalhandler implementation:
[Property Change Signal Handler]
The signal handler syntax for property change is as follows on <Property> Changed, <Property> is the name of the property, the first letter should be capitalized. For example, although the TextInput type document does not define the textChanged signal, this signal is available because TextInput has a text attribute. Therefore, we can also implement the onTextChanged signal handler, which will be called when the property value is changed:
Method Properties
An object's method is called when it performs some processing or triggers some events. When a method is connected to a signal, these methods are executed when the signal is transmitted.
[Define method attributes]
We can use Q_INVOKABLE to register to the QML type system through functions in C ++ classes or Q_SLOT in C ++ classes. Optionally, we can also add custom methods to the object in the QML document:
Methods can be added to QML types to define separate reusable JavaScript code. These methods can be called internally or by external objects.
Unlike signals, there is no need to define parameter types here, because they default to var type.
Views that define two methods or signals with the same name in the same type block will cause errors. However, we can use the name of an existing method to define a new method (this will make the existing method unusable)
The following Rectangle type has a calculateHeight () method, which is called when the height value is specified.
If the method has parameters, then we can access them by parameter name in the method. For example, if MouseArea is clicked, then the moveTo () method will be called, and the new position of the text can be set using newX and newY:
Additional attributes and additional SignalHandler
Additional attributes and additional signal processing mechanisms allow objects to use external attributes and signal handlers that are not referenced by the object. This allows objects to access those properties and signals associated with a single object.
A QML type implementation may choose to create additional specific attributes and signals. Instantiating this type is created at runtime, allowing these objects to access properties and signals.
The syntax for referencing additional attributes and handlers is as follows:
For example, the ListView type has an additional property ListView.isCurrentItem, which can be accessed by every agent of ListView. This attribute can be used by each independent proxy object to determine which item is currently selected:
In this case, the name of the additional type is ListView and the property isCurrentItem, and the additional property is referenced using ListView.isCurrentItem.
Additional signal handlers can also be referenced in this way. For example, the additional signal handler is Component.isCompleted, which can be used to execute some JavaScript code when the component creation process is completed. In the following example, once the ListModel is completely created, the Component.onCompleted signal handler will be automatically executed:
The additional type names are Component and completed signals. Additional signal handlers can be referenced like this: Component.isCompleted.
[Notes on accessing additional attributes and Signal Handler]
A common mistake is to set additional properties and signal handlers to be directly accessible from sub-objects. This is not a problem. Instances of additional types are only added to specific objects, not the object and all its sub-objects.
For example: the following example is an adapted version of the previous additional attribute example. In this case, the agent is an Item, and the Rectangle is the child object of the Item:
This does not work as expected, because ListView.isCurrentItem is only attached to the root proxy object, not its children. Since Rectangle is a child object of the agent, not the agent itself, he cannot use ListView.isCurrentItem to access additional properties of isCurrentItem. Therefore, the rectangle must access the isCurrentItem property through the root proxy object:
Now it is possible to correctly refer to the isCurrentItem attached property of the delegate through delegateItem.ListView.isCurrentItem.
