****************************************************************************/
/*!
\page qtqml-cppclasses-topic.html
-\title C++ Classes Provided By The Qt QML Module
+\title C++ Classes Provided by the Qt QML Module
\brief Overview of the C++ classes provided by the Qt QML module
The Qt QML module provides C++ classes which implement the QML framework.
****************************************************************************/
/*!
\page qtqml-cppintegration-data.html
-\title Exposing Data From C++ To QML
+\title Exposing Data from C++ to QML
\brief Description of how to expose data from C++ to QML
-\section1 Supported data types
+\section1 Supported Data Types
Any C++ data that is used from QML - whether as custom properties, or parameters for signals or
functions - must be of a type that is recognizable by QML.
-\section1 Data Returned From Instance Method Invocation
+\section1 Data Returned from Instance Method Invocation
A registered C++ type may have functions flagged with the
Q_INVOKABLE flag defined. Those functions of an instance of
****************************************************************************/
/*!
\page qtqml-cppintegration-functions.html
-\title Exposing C++ Functionality To QML
+\title Exposing C++ Functionality to QML
\brief Description of how to expose functionality defined in C++ to QML
-\section1 Properties Of Types Defined In C++
+\section1 Properties of Types Defined in C++
Any \l {The Property System}{Qt properties} - that is, those declared with the Q_PROPERTY()
macro - are accessible from QML. Here is a modified version of the \l {Embedding C++ objects into
notified when the value changes. If you are using custom types in QML, make sure their
properties have NOTIFY signals so that they can be used in property bindings.
-\section1 Signals And Slots
+\section1 Signals and Slots
QML integrates with the normal Qt C++ signals and slots system.
Signal handlers may be defined in a QML object, to handle signals
****************************************************************************/
/*!
\page qtqml-cppintegration-reverse.html
-\title Interacting With QML Objects From C++
+\title Interacting with QML Objects from C++
\brief Description of how to interact with QML objects from C++
-\section1 QML Objects, QObject And QMetaObject
+\section1 QML Objects, QObject and QMetaObject
QML object types are, internally, QObject-derived types. Each type has an
associated QMetaObject, and all functions, properties and signals of an
instance of a QML object type can be accessed through the QMetaObject.
-\section1 Accessing QML Objects From C++
+\section1 Accessing QML Objects from C++
Once you have a pointer to a QML object in C++, you can access its properties,
invoke its functions, and connect to its signals. To get such a pointer, a
-\section2 Object Name And findChild
+\section2 Object Name and findChild
NOTE: this is only applicable to QML object types provided by the Qt Quick
module.
required \c objectName. It is better for the C++ implementation to know as little as possible about
the QML user interface implementation and the composition of the QML object tree.
-\section2 Passed As Arguments
+\section2 Passed as Arguments
Any QML object may be passed as an argument to a Q_INVOKABLE C++ function
if that function has a pointer to a QObject as a parameter. The object
same name but different arguments, the correct function will be called according to the number and
the types of arguments that are provided.
-\section1 Signals And Slots
+\section1 Signals and Slots
All QML signals are automatically available to C++, and can be connected to using QObject::connect()
like any ordinary Qt C++ signal. In return, any C++ signal can be received by a QML object using
****************************************************************************/
/*!
\page qtqml-cppintegration-topic.html
-\title Integrating QML And C++
+\title Integrating QML and C++
\brief Description of how to integrate QML and C++ code
QML was designed to allow tight integration with C++ code. This allows hybrid
\endlist
-\section1 Exposing C++ Types To QML
+\section1 Exposing C++ Types to QML
QML types may be implemented in C++ and then exposed to the QML type system via
plugins or type registration. This is covered in more detail elsewhere in the
documentation; see the documentation regarding
\l{qtqml-cppintegration-registercpptypes.html}
-{Registering C++ Types With The QML Type System} for more information on that
+{Registering C++ Types with the QML Type System} for more information on that
topic.
For more information on the specifics of how to define C++ types for use in QML
about defining \l{qtqml-modules-cppplugins.html#creating-a-plugin}
{C++ types for use in QML}.
-\section1 Exposing C++ Data To QML
+\section1 Exposing C++ Data to QML
Data from C++ may be exposed to QML via context properties, instance
properties, or by returning data from Q_INVOKABLE methods. For more
information about each of these approaches, and the ownership semantics
applicable to each, see the documentation on \l{qtqml-cppintegration-data.html}
-{Exposing C++ Data To QML}.
+{Exposing C++ Data to QML}.
-\section1 Exposing C++ Functions To QML
+\section1 Exposing C++ Functions to QML
Functions from C++ may be exposed to QML via signals and slots, by tagging a
function declaration with the Q_INVOKABLE macro, or by registering the C++ type
as a module API and installing that module API into a particular namespace.
For more information about these approaches, see the documentation on
-\l{qtqml-cppintegration-functions.html}{Exposing C++ Functionality To QML}.
+\l{qtqml-cppintegration-functions.html}{Exposing C++ Functionality to QML}.
-\section1 Interacting With Objects Defined In QML From C++
+\section1 Interacting with Objects Defined in QML from C++
Most properties of an object defined in QML may be accessed via
QQmlProperty::read() or QObject::property(). If the property is a list
For more information about accessing QML objects from C++, see the
documentation on \l{qtqml-cppintegration-reverse.html}
-{Interacting With Objects Defined In QML From C++}.
+{Interacting with Objects Defined in QML from C++}.
*/
\note the letter case of the file name is significant on some (notably UNIX) filesystems. It is recommended the file name case matches the case of the desired QML type name exactly - for example, \c Box.qml and not \c BoX.qml - regardless of the platform to which the QML type will be deployed.
-\section2 Importing types defined outside the current directory
+\section2 Importing Types Defined Outside the Current Directory
If \c SquareButton.qml was not in the same directory as \c myapplication.qml,
the \c SquareButton type would need to be specifically made available through an \e import statement in \c myapplication.qml. It could be imported from a relative path on the file system, or as an installed module; see \l {QML Modules}{module} for more details.
enabler to allow clients to write modular, highly readable and maintainable
code.
-\section1 Structure Of A QML Document
+\section1 Structure of a QML Document
A QML document consists of two sections: the imports section, and the object
declaration section. The imports section in a document contains import
/*!
\page qtqml-javascript-dynamicobjectcreation.html
-\title Dynamic QML object creation from JavaScript
+\title Dynamic QML Object Creation from JavaScript
\brief instantiating and managing QML objects from JavaScript
QML supports the dynamic creation of objects from within JavaScript. This is
****************************************************************************/
/*!
\page qtqml-javascript-expressions.html
-\title JavaScript Expressions In QML Documents
+\title JavaScript Expressions in QML Documents
\brief Description of where JavaScript expressions are valid in QML documents
\li \l{QML Object Attributes#custom-methods}{custom methods} can be defined
in QML files as JavaScript functions
\li JavaScript files providing functions and variables can be
- \l{Importing JavaScript Files In QML Documents}{imported} in a QML
+ \l{Importing JavaScript Files in QML Documents}{imported} in a QML
document
\endlist
\snippet qml/integrating-javascript/scarceresources/avatarExample.cpp 4
-\section2 Example Five: Explicit Destruction And JavaScript References
+\section2 Example Five: Explicit Destruction and JavaScript References
One thing to be aware of when using "var" type properties is that they
hold references to JavaScript objects. As such, if multiple references
****************************************************************************/
/*!
\page qtqml-javascript-imports.html
-\title Importing JavaScript Files In QML Documents
+\title Importing JavaScript Files in QML Documents
\brief Description of how to import and use JavaScript files in QML documents
Both relative and absolute JavaScript URLs can be imported in QML documents.
defined in the importing QML document, via the \c{"Qualifier.functionName()"}
syntax.
-\section1 Importing One JavaScript File From Another
+\section1 Importing a JavaScript File from Another
In QtQuick 2.0, support has been added to allow JavaScript files to import
other JavaScript files and also QML type namespaces using a variation of the
objects or properties directly, although QML values can be passed as function
parameters.
-\section1 Including One JavaScript File From Another
+\section1 Including a JavaScript File from Another
When a JavaScript file is imported, it must be imported with a qualifier. The
functions in that file are then accessible from the importing script via the
****************************************************************************/
/*!
\page qtqml-javascript-topic.html
-\title Integrating QML And JavaScript
+\title Integrating QML and JavaScript
\brief Description of how to use JavaScript in QML applications
The QML language uses a JSON-like syntax and allows various expressions and
are JavaScript expressions.
See the documentation page titled
-\l{qtqml-javascript-expressions.html}{JavaScript Expressions In QML Documents}
+\l{qtqml-javascript-expressions.html}{JavaScript Expressions in QML Documents}
for more information about using JavaScript expressions in QML.
\section1 JavaScript Imports
A QML document may import JavaScript files. This allows an application
developer to provide application logic in modular, self-contained files.
See the documentation page titled
-\l{qtqml-javascript-imports.html}{Importing JavaScript Files In QML Documents}
+\l{qtqml-javascript-imports.html}{Importing JavaScript Files in QML Documents}
for more information on how to import JavaScript files and how to use the
functionality they provide.
/*!
\page qtqml-modules-cppplugins.html
-\title Creating C++ Plugins For QML
+\title Creating C++ Plugins for QML
\brief Description of how to write C++ plugins for QML
-\section1 Creating A Plugin
+\section1 Creating a Plugin
The \l{QQmlEngine}{QML engine} load C++ plugins for QML.
Such plugins are usually provided in a QML extension module, and can
Modules} documentation for more information.
-\section1 Writing a qmldir file
+\section1 Writing a qmldir File
A \c qmldir file contains one or more lines of the following commands:
MyScript 1.0 MyScript.js
\endcode
- See \l{qtqml-javascript-imports.html}{Importing JavaScript Files In QML Documents} for
+ See \l{qtqml-javascript-imports.html}{Importing JavaScript Files in QML Documents} for
more information.
\row
\l{examples/qml/cppextensions/plugins} for an example that uses C++ plugins.
-\section1 Writing a qmltypes file
+\section1 Writing a qmltypes File
QML modules may refer to one or more type information files in their
\c qmldir file. These usually have the \c .qmltypes
See \l{qtqml-modules-qmldir.html}{Adding Module Metadata with a qmldir File} for more information.
-\section1 Providing Types And Functionality In A C++ Plugin
+\section1 Providing Types and Functionality in a C++ Plugin
An application which has a lot of logic implemented in C++, or which defines
types in C++ and exposes them to QML, may wish to implement a QML plugin. A
standalone documents of QML code. These can be used to define \l {QML Object Types}{QML object types} that can then be reused throughout an application.
-\section1 Import statements
+\section1 Import Statements
A QML document may have one or more imports at the top of the file.
An import can be any one of:
documentation for in-depth information about QML imports.
-\section1 Object declarations
+\section1 Object Declarations
Syntactically, a block of QML code defines a tree of QML objects to be created. Objects are
defined using \e {object declarations} that describe the type of object to be created as well
Obviously, the \l Rectangle object declared in this example is very simple indeed, as it defines nothing more than a few property values. To create more useful objects, an object declaration may define many other types of attributes: these are discussed in the \l{qtqml-syntax-object-declaration.html}{Object Declarations} documentation. Additionally, an object declaration may define child objects, as discussed below.
-\section2 Child objects
+\section2 Child Objects
Any object declaration can define child objects through nested object declarations. In this way, \b {any object declaration implicitly declares an object tree that may contain any number of child objects}.
\title Import Statements
\brief Description of import statements in QML
-\section1 Syntax Of An Import Statement
+\section1 Syntax of an Import Statement
The \c import statement is used to provide the QML engine with access to the modules that define the types that are referred to from within the QML file.
that object type. There are several different kinds of attributes which
can be specified, which are described below.
-\section1 Attributes in object declarations
+\section1 Attributes in Object Declarations
An \l{qtqml-syntax-basics.html#object-declarations}{object declaration} in a
QML document defines a new type. It also declares an object hierarchy that
These attributes are discussed in detail below.
-\section2 The \e id attribute
+\section2 The \e id Attribute
Every QML object type has exactly one \e id attribute. This attribute is
provided by the language itself, and cannot be redefined or overridden by any
example.
-\section2 Property attributes
+\section2 Property Attributes
A property is an attribute of an object that can be assigned a static value
or bound to a dynamic expression. A property's value can be read by other
objects. Generally it can also be modified by another object, unless a
particular QML type has explicitly disallowed this for a specific property.
-\section3 Defining property attributes
+\section3 Defining Property Attributes
A property may be defined for a type in C++ by registering a
Q_PROPERTY of a class which is then registered with the QML type system.
letters, numbers and underscores. \l {JavaScript Reserved Words}
{JavaScript reserved words} are not valid property names. The \c default
keyword is optional, and modifies the semantics of the property being declared.
-See the upcoming section on \l {Default properties}{default properties} for
+See the upcoming section on \l {Default Properties}{default properties} for
more information about the \c default property modifier.
Declaring a custom property implicitly creates a value-change
}
\endqml
-\section4 Valid types in custom property definitions
+\section4 Valid Types in Custom Property Definitions
The following types can be used as custom property types:
\c ColorfulButton would also be valid.
-\section3 Values of property attributes
+\section3 Values of Property Attributes
The value of a property of an object instance may specified in an
object declaration in two separate ways:
The value in either case may be either a binding expression or a static value.
-\section4 Value assignment on initialization
+\section4 Value Assignment on Initialization
The syntax for assigning a value to a property on initialization is:
}
\endqml
-\section4 Imperative value assignment
+\section4 Imperative Value Assignment
An imperative value assignment is where a property value (either static value
or binding expression) is assigned to a property from imperative JavaScript
}
\endqml
-\section4 Valid property values
+\section4 Valid Property Values
As previously noted, there are two kinds of values which may be assigned to a
property: static values, and binding expression values.
information on the topic.
-\section3 Type safety
+\section3 Type Safety
Properties are type safe. A property can only be assigned a value that matches
the property type.
supported by default. Additionally, any available \l {QML Object Types}
{QML object type} may also be used as a property type.
-\section3 Special property types
+\section3 Special Property Types
-\section4 Object list property attributes
+\section4 Object List Property Attributes
A \l list type property can be assigned a list of QML object-type values.
The syntax for defining an object list value is a comma-separated list
\l{QML Basic Types} for more information.
-\section3 Property aliases
+\section3 Property Aliases
Property aliases are properties which hold a reference to another property.
Unlike an ordinary property definition, which allocates a new, unique storage
the other way around.
-\section4 Considerations for property aliases
+\section4 Considerations for Property Aliases
Aliases are only activated once a component has been fully initialized. An
error is generated when an uninitialized alias is referenced. Likewise,
property and refer to the actual defined property rather than the alias.
-\section3 Default properties
+\section3 Default Properties
An object definition can have a single \e default property. A default property
is the property to which a value is assigned if an object is declared within
children of an inner ListView.
-\section2 Signal attributes
+\section2 Signal Attributes
A signal is a notification from an object that some event has occurred: for
example, a property has changed, an animation has started or stopped, or
}
\endqml
-\section3 Defining signal attributes
+\section3 Defining Signal Attributes
A signal may be defined for a type in C++ by registering a Q_SIGNAL of a class
which is then registered with the QML type system. Alternatively, a custom
is emitted, and handlers can use the defined signal argument names to access
the respective arguments.
-\section3 Property change signals
+\section3 Property Change Signals
QML types also provide built-in \e {property change signals} that are emitted
whenever a property value changes, as previously described in the section on
information about why these signals are useful, and how to use them.
-\section2 Signal handler attributes
+\section2 Signal Handler Attributes
Signal handlers are a special sort of \l{Method attributes}{method attribute},
where the method implementation is invoked by the QML engine whenever the
See the \l {Signal and Handler Event System} for more details on use of
signals.
-\section3 Property change signal handlers
+\section3 Property Change Signal Handlers
Signal handlers for property change signal take the syntax form
\e on<Property>Changed where \e <Property> is the name of the property,
\endqml
-\section2 Method attributes
+\section2 Method Attributes
A method of an object type is a function which may be called to perform some
processing or trigger further events. A method can be connected to a signal so
that it is automatically invoked whenever the signal is emitted. See
\l {Signal and Handler Event System} for more details.
-\section3 Defining method attributes
+\section3 Defining Method Attributes
A method may be defined for a type in C++ by tagging a function of a class
which is then registered with the QML type system with Q_INVOKABLE or by
\endqml
-\section2 Attached properties and attached signal handlers
+\section2 Attached Properties and Attached Signal Handlers
\e {Attached properties} and \e {attached signal handlers} are mechanisms that
enable objects to be annotated with extra properties or signal handlers that
\c Component.isCompleted.
-\section3 A note about accessing attached properties and signal handlers
+\section3 A Note About Accessing Attached Properties and Signal Handlers
A common error is to assume that attached properties and signal handlers are
directly accessible from the children of the object to which these attributes
\keyword qml-javascript-assignment
-\section1 Creating property bindings from JavaScript
+\section1 Creating Property Bindings from JavaScript
Once a property has been bound to an expression, the property is set to be automatically updated as necessary. However, be aware that if the property is later assigned a static value from a JavaScript statement, this will remove the binding.
Now when the space key is pressed, a new binding of \c width*3 is assigned, instead of simply removing the initial binding.
-\section2 Using \c this with property binding
+\section2 Using \c this with Property Binding
When creating a property binding from JavaScript, QML allows the use of the \c
this keyword to refer to the object to which the property binding will be
operations in the handler allows the component to respond to the event.
\keyword qml-signals-and-handlers
-\section1 Receiving signals with signal handlers
+\section1 Receiving Signals with Signal Handlers
To receive a notification when a particular signal is emitted for a particular object, the object definition should declare a signal handler named \e on<Signal> where \e <Signal> is the name of the signal, with the first letter capitalized. The signal handler should contain the JavaScript code to be executed when the signal handler is invoked.
\endqml
-\section2 Property change signal handlers
+\section2 Property Change Signal Handlers
A signal is automatically emitted when the value of a QML property changes. This type of signal is a \e {property change signal} and signal handlers for these signals are written in the form \e on<Property>Changed where \e <Property> is the name of the property, with the first letter capitalized.
Even though the \l MouseArea documentation does not document a signal handler named \c onPressedChanged, the signal is implicitly provided by the fact that the \c pressed property exists.
-\section2 Using the Connections type
+\section2 Using the Connections Type
In some cases it may be desirable to access a signal outside of the object that emits it. For these purposes, the QtQuick module provides the \l Connections type for connecting to signals of arbitrary objects. A \l Connections object can receive any signal from its specified \l {Connection::target}{target}.
\endqml
-\section2 Attached signal handlers
+\section2 Attached Signal Handlers
An \l {attached signal handler} is a signal handler that receives a signal from an \e {attaching type} rather than the object within which the handler is declared.
See \l {Attached properties and attached signal handlers} for more information on attached signal handlers.
-\section1 Adding signals to custom QML types
+\section1 Adding Signals to Custom QML Types
Signals can be added to custom QML types through the \c signal keyword.
converted into a \c url value, and vice-versa.
- \section1 Using the url type
+ \section1 Using the url Type
When a relative URL is written to a \c url type property, it is converted
into a URL object, so \bold {matching the URL value against the input string
converted into a \c list value, and vice-versa.
- \section1 Using the list type
+ \section1 Using the list Type
For example, the \l Item type has a \l {Item::}{states} list-type property that
can be assigned to and used as follows:
type, as discussed in \l {qtqml-documents-definetypes.html}
{Documents as QML object type definitions}, or by defining a QML type from C++
and registering the type with the QML engine, as discussed in
-\l{qtqml-registercpptypes.html}{Registering C++ Types With The QML Type System}.
+\l{qtqml-registercpptypes.html}{Registering C++ Types with the QML Type System}.
\section1 Creating Object Types from QML
other available property types.
-\section1 JavaScript types
+\section1 JavaScript Types
JavaScript objects and arrays are supported by the QML engine. Any standard
JavaScript type can be created and stored using the generic \l var type.
\li New QQmlEngine::trimComponentCache() method safely discards unused data in the engine's component cache to free memory.
\endlist
-\section2 Component and Object creation
+\section2 Component and Object Creation
\list
\li QML objects can now be created asynchronously to improve application performance.
projects / profile / ivi / qtdeclarative.git / commitdiff