|
|
              
QML ComponentsA component is an instantiable QML definition, typically contained in a .qml file. For instance, a Button component may be defined in Button.qml file. The QML engine may instantiate this Button component to create Button objects. Alternatively, a component may be defined inside a Component element. Moreover, the Button definition may also contain other components. A Button component might have a Text element for its label and other components to implement its functions. Compounding components to form new components is the emphasis in QML. Defining New ComponentsAny snippet of QML code may become a component, by placing the code in a QML file, whose file extension is .qml). A complete Button component that responds to user input may be in a Button.qml file. The component name, Button, matches the QML filename, Button.qml. Also, the first character is in upper case. Matching the names allow components in the same directory to be in the direct import path of the application. The section on Importing a Component has information about naming components with different filenames. Alternatively, a Component element may encapsulate a QML object to form a component. Components may incorporate any QML feature such as:
For information about these features, visit the respective overviews or the main Qt Quick reference page. Loading a ComponentThe initialization of inline components is different from loading a component from a .qml file. Importing a ComponentA component defined in a .qml file is directly usable by declaring the name of the component. For example, a button defined in Button.qml is created by declaring a Button. The button is defined in the Defining New Components section. Note that the component name, Button, matches the QML filename, Button.qml. Also, the first character is in upper case. Matching the names allow components in the same directory to be in the direct import path of the application. For flexibility, a qmldir file is for dictating which additional components, plugins, or directories should be imported. By using a qmldir file, component names do not need to match the filenames. The qmldir file should, however, be in an imported path. Loading an Inline ComponentA consequence of inline components is that initialization may be deferred or delayed. A component may be created during a MouseArea event or by using a Loader element. The component can create an object, which is addressable in a similar way as an identifier. Thus, the created object may have its bindings set and read like a normal QML object. Component PropertiesInitializing a component, either from a .qml file or initializing an inline component, have several properties to facilitate component execution. Specifically, there are attached properties and attached signal handlers for setting properties during the lifetime of a component. The Component.onCompleted attached signal handler is called when the component completes initialization. It is useful for executing any commands after component initialization. Similarly, the Component.onDestruction signal handler executes when the component finishes destruction. Top-Level ComponentChoosing the top-level or the root object of components is an important design aspect because the top-level object dictates which properties are accessible outside the component. Some elements are not visual elements and will not have visual properties exposed outside the component. Likewise, some elements add functionality that are not available to visual elements. Consider the Button component from the Defining New Components section; it's top-level object is a Rectangle. When imported, the Button component will possess the Rectangle's properties, methods, signals, and any custom properties. The Button's text alias is accessible from outside the component as well as the Rectangle's visual properties and signals such as x, y, anchors, and states. Alternatively, we may choose a FocusScope as our top-level object. The FocusScope element manage keyboard focus for its children which is beneficial for certain types of interfaces. However, since FocusScopes are not visual elements, the visual properties of its child need to be exposed. The Object IdentifierEach QML object may be given a special unique identifier called an id. No other object within the same QML component (see QML Documents) can have the same id value. QML objects may then access an object using the id property. A component may readily access its parent's properties by using the parent property. Note that an id must begin with a lower-case letter or an underscore. The id cannot contain characters other than letters, numbers, underscores, and JavaScript reserved words. Child ComponentsObjects or Items declared within a component can be made accessible by binding their id to a property alias. The advantage of using an alias instead a property of type of the object is that the value of the alias cannot be overridden, and members of the object can be used in property bindings when declaring an instance of the component. If a property of type Text was used instead of an alias in this instance there would be no guarantee that label would be initialized before the binding was attempted which would cause the binding to fail. |
