\e commands are deprecated and are only supported through an alias.
We should use the official command and not the deprecated command.
Change-Id: Icf88b9cda673f436dd855f22960112d0a37c74eb
Reviewed-on: http://codereview.qt-project.org/5918
Reviewed-by: Qt Sanity Bot <qt_sanity_bot@ovi.com>
Reviewed-by: Bea Lam <bea.lam@nokia.com>
Reviewed-by: Alan Alpert <alan.alpert@nokia.com>
It assumes that you already know the basics of QML (for example, from reading the
\l{QML Tutorial}{simple tutorial}).
-In this tutorial we write a game, \e {Same Game}, based on the Same Game application
+In this tutorial we write a game, \i {Same Game}, based on the Same Game application
included in the declarative \c examples directory, which looks like this:
\image declarative-samegame.png
\title Anchor-based Layout in QML
In addition to the more traditional \l Grid, \l Row, and \l Column,
-QML also provides a way to layout items using the concept of \e anchors.
+QML also provides a way to layout items using the concept of \i anchors.
Each item can be thought of as having a set of 7 invisible "anchor lines":
\l {Item::anchors.left}{left}, \l {Item::anchors.horizontalCenter}{horizontalCenter},
\l {Item::anchors.right}{right}, \l {Item::anchors.top}{top},
\image edges_qml.png
The baseline (not pictured above) corresponds to the imaginary line on which
-text would sit. For items with no text it is the same as \e top.
+text would sit. For items with no text it is the same as \i top.
The QML anchoring system allows you to define relationships between the anchor lines of different items. For example, you can write:
Rectangle { id: rect2; anchors.left: rect1.right; ... }
\endcode
-In this case, the left edge of \e rect2 is bound to the right edge of \e rect1, producing the following:
+In this case, the left edge of \i rect2 is bound to the right edge of \i rect1, producing the following:
\image edge1.png
\image edge3.png
By specifying multiple horizontal or vertical anchors you can control the size of an item. Below,
-\e rect2 is anchored to the right of \e rect1 and the left of \e rect3. If either of the blue
-rectangles are moved, \e rect2 will stretch and shrink as necessary:
+\i rect2 is anchored to the right of \i rect1 and the left of \i rect3. If either of the blue
+rectangles are moved, \i rect2 will stretch and shrink as necessary:
\code
Rectangle { id: rect1; x: 0; ... }
\section1 Anchor Margins and Offsets
-The anchoring system also allows \e margins and \e offsets to be specified for an item's anchors.
+The anchoring system also allows \i margins and \i offsets to be specified for an item's anchors.
Margins specify the amount of empty space to leave to the outside of an item's anchor, while
offsets allow positioning to be manipulated using the center anchor lines. An item can
specify its anchor margins individually through \l {Item::anchors.leftMargin}{leftMargin},
Rectangle { id: rect2; anchors.left: rect1.right; anchors.leftMargin: 5; ... }
\endcode
-In this case, a margin of 5 pixels is reserved to the left of \e rect2, producing the following:
+In this case, a margin of 5 pixels is reserved to the left of \i rect2, producing the following:
\image edge2.png
-\note Anchor margins only apply to anchors; they are \e not a generic means of applying margins to an \l Item.
+\note Anchor margins only apply to anchors; they are \i not a generic means of applying margins to an \l Item.
If an anchor margin is specified for an edge but the item is not anchored to any item on that
edge, the margin is not applied.
\snippet doc/src/snippets/declarative/animation.qml direct property change
-However, to create more control, \e {property animations} apply smooth movements
+However, to create more control, \i {property animations} apply smooth movements
by interpolating values between property value changes. Property animations
provide timing controls and allows different interpolations through
\l{qml-easing-animation}{easing curves}.
\section2 Default Animation as Behaviors
-Default property animations are set using \e {behavior animations}. Animations
+Default property animations are set using \i {behavior animations}. Animations
declared in \l {Behavior} elements apply to the property and animates any
property value changes. However, Behavior elements have an
\c enabled property to purposely enable or disable the behavior animations.
\section1 Playing Animations in Parallel or in Sequence
-Animations can run \e {in parallel} or \e {in sequence}. Parallel animations
+Animations can run \i {in parallel} or \i {in sequence}. Parallel animations
will play a group of animations at the same time while sequential animations
play a group of animations in order: one after the other. Grouping animations in
\l{SequentialAnimation} and \l{ParallelAnimation} will play the animations in
\o PauseAnimation: enables pauses during animations
\o ScriptAction: allows JavaScript to be executed during an animation, and can
be used together with StateChangeScript to reused existing scripts
-\o PropertyAction: changes a property \e immediately during an animation,
+\o PropertyAction: changes a property \i immediately during an animation,
without animating the property change
\endlist
\endqml
While this is a convenient way to store array and map-type values, you
- must be aware that the \c items and \c attributes properties above are \e not
+ must be aware that the \c items and \c attributes properties above are \i not
QML objects (and certainly not JavaScript object either) and the key-value
- pairs in \c attributes are \e not QML properties. Rather, the \c items
+ pairs in \c attributes are \i not QML properties. Rather, the \c items
property holds an array of values, and \c attributes holds a set of key-value
pairs. Since they are stored as a set of values, instead of as an object,
- their contents \e cannot be modified individually:
+ their contents \i cannot be modified individually:
\qml
Item {
One way to "update" the contents of an array or map is to copy the property
to a JavaScript object, modify the copy as desired, and then reassign the
property to the updated copy. Note, however, that this is not efficient.
- In the example below, which reassigns the \c attributes property, the \e entire
+ In the example below, which reassigns the \c attributes property, the \i entire
set of key-value pairs must be serialized and deserialized every time it is
copied between a JavaScript object and a QML property:
within a JavaScript file.
JavaScript programmers should also note that when a JavaScript object is
- copied to an array or map property, the \e contents of the object (that is,
+ copied to an array or map property, the \i contents of the object (that is,
its key-value properties) are copied, rather than the object itself. The
property does not hold a reference to the original JavaScript object, and
extra data such as the object's JavaScript prototype chain is also lost in
For better readability, we separate these different parts with an empty line.
-For example, a hypothetical \e photo QML object would look like this:
+For example, a hypothetical \i photo QML object would look like this:
\snippet doc/src/snippets/declarative/codingconventions/photo.qml 0
\section1 Grouped Properties
If using multiple properties from a group of properties,
-we use the \e {group notation} rather than the \e {dot notation} to improve readability.
+we use the \i {group notation} rather than the \i {dot notation} to improve readability.
For example, this:
QML and JavaScript do not enforce private properties like C++. There is a need
to hide these private properties, for example, when the properties are part of
the implementation. As a convention, private properties begin with two
-\e underscore characters. For example, \c __area, is a property that is
+\i underscore characters. For example, \c __area, is a property that is
accessible but is not meant for public use. Note that QML and JavaScript will
grant the user access to these properties.
\o a \c on property (the interface to interact with the switch),
\o two images (the background image and the knob),
\o two mouse regions for user interation (on the background image and on the knob),
-\o two states (a \e on state and a \e off state),
+\o two states (a \i on state and a \i off state),
\o two functions or slots to react to the user interation (\c toggle() and \c dorelease()),
\o and a transition that describe how to go from one state to the other.
\endlist
We define the two states of the switch:
\list
-\o In the \e on state the knob is on the right (\c x position is 78) and the \c on property is \c true.
-\o In the \e off state the knob is on the left (\c x position is 1) and the \c on property is \c false.
+\o In the \i on state the knob is on the right (\c x position is 78) and the \c on property is \c true.
+\o In the \i off state the knob is on the left (\c x position is 1) and the \c on property is \c false.
\endlist
For more information on states see \l{qmlstates}{QML States}.
\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 2
This first function is called when the background image or the knob are clicked. We simply want the switch to toggle between the two
-states (\e on and \e off).
+states (\i on and \i off).
\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 3
This second function is called when the knob is released and we want to make sure that the knob does not end up between states
-(neither \e on nor \e off). If it is the case call the \c toggle() function otherwise we do nothing.
+(neither \i on nor \i off). If it is the case call the \c toggle() function otherwise we do nothing.
For more information on scripts see \l{Integrating JavaScript}.
\endlist
When a property of a supported type is added to a C++ class, in a QML
-element based on the C++ class, a \e{value-changed} signal handler
+element based on the C++ class, a \i{value-changed} signal handler
will be available. See \l{Signal Support} below.
QML is typesafe. Attempting to assign an invalid value to a property
-will generate an error. For example, assuming the \e{name} property
+will generate an error. For example, assuming the \i{name} property
of the \c Person element had a type of QString, this would cause an
error:
and features to be added to existing elements without breaking existing programs.
QML enables this by allowing the properties, methods and signals of a class to be tagged with
-a particular \e revision, so that they are only accessible if the relevant module version
+a particular \i revision, so that they are only accessible if the relevant module version
is imported. In this case, the author can tag the \c root property as being added in
-\e {revision 1} of the class, and register that revision in version 1.1 of the module.
+\i {revision 1} of the class, and register that revision in version 1.1 of the module.
The REVISION tag is used to mark the \c root property as added in revision 1 of the class.
Methods such as Q_INVOKABLE's, signals and slots can also be tagged for a
The QML snippet shown above assigns a collection of objects to the
\c BirthdayParty's default property.
-The \e {default property} is a syntactic convenience that allows a type designer to
+The \i {default property} is a syntactic convenience that allows a type designer to
specify a single property as the type's default. The default property is
assigned to whenever no explicit property is specified. As a convenience, it is
behaviorally identical to assigning to the default property explicitly by name.
\a object is destroyed.
\endquotation
-Conceptually, attached properties are a \e type exporting a set of additional
-properties that can be set on \e any other object instance. Attached properties
+Conceptually, attached properties are a \i type exporting a set of additional
+properties that can be set on \i any other object instance. Attached properties
cannot be limited to only attaching to a sub-set of object instances, although
their effect may be so limited.
signals with the \l {Connections} element.
Additionally, if a property is added to a C++ class, all QML elements
-based on that C++ class will have a \e{value-changed} signal handler
+based on that C++ class will have a \i{value-changed} signal handler
for that property. The name of the signal handler is
-\e{on<Property-name>Changed}, with the first letter of the property
+\i{on<Property-name>Changed}, with the first letter of the property
name being upper case.
\note The QML signal handler will always be named
When a key is pressed or released, a key event is generated and delivered to the
focused QML \l Item. To facilitate the construction of reusable components
and to address some of the cases unique to fluid user interfaces, the QML items add aged
-\e scope based extension to Qt's traditional keyboard focus model.
+\i scope based extension to Qt's traditional keyboard focus model.
\tableofcontents
\o If the Qt widget containing the \l QDeclarativeView has focus, the key event
is delivered to it. Otherwise, regular Qt key handling continues.
\o The key event is delivered by the scene to the QML \l Item with
-\e {active focus}. If no Item has active focus, the key event is
+\i {active focus}. If no Item has active focus, the key event is
\l {QEvent::ignore()}{ignored} and regular Qt key handling continues.
\o If the QML Item with active focus accepts the key event, propagation
stops. Otherwise the event is "bubbled up", by recursively passing it to each
Likewise, the \c window component does not have the ability to know if its
imported components are requesting the focus.
-To solve this problem, the QML introduces a concept known as a \e {focus scope}.
+To solve this problem, the QML introduces a concept known as a \i {focus scope}.
For existing Qt users, a focus scope is like an automatic focus proxy.
A focus scope is created by declaring the \l FocusScope element.
\image declarative-qmlfocus3.png
-Conceptually \e {focus scopes} are quite simple.
+Conceptually \i {focus scopes} are quite simple.
\list
\o Within each focus scope one element may have \c {Item::focus} set to
\c true. If more than one \l Item has the \c focus property set, the
as many popular web browsers with following exceptions:
\list
\i QML's XMLHttpRequest does not enforce the same origin policy.
-\i QML's XMLHttpRequest does not support \e synchronous requests.
+\i QML's XMLHttpRequest does not support \i synchronous requests.
\endlist
Additionally, the \c responseXML XML DOM tree currently supported by QML is a reduced subset
\section3 db = openDatabaseSync(identifier, version, description, estimated_size, callback(db))
-Returns the database identified by \e identifier. If the database does not already exist, it
-is created, and the function \e callback is called with the database as a parameter. \e description
-and \e estimated_size are written to the INI file (described below), but are otherwise currently
+Returns the database identified by \i identifier. If the database does not already exist, it
+is created, and the function \i callback is called with the database as a parameter. \i description
+and \i estimated_size are written to the INI file (described below), but are otherwise currently
unused.
May throw exception with code property SQLException.DATABASE_ERR, or SQLException.VERSION_ERR.
\section3 db.changeVersion(from, to, callback(tx))
-This method allows you to perform a \e{Scheme Upgrade}.
+This method allows you to perform a \i{Scheme Upgrade}.
-If the current version of \e db is not \e from, then an exception is thrown.
+If the current version of \i db is not \i from, then an exception is thrown.
-Otherwise, a database transaction is created and passed to \e callback. In this function,
-you can call \e executeSql on \e tx to upgrade the database.
+Otherwise, a database transaction is created and passed to \i callback. In this function,
+you can call \i executeSql on \i tx to upgrade the database.
May throw exception with code property SQLException.DATABASE_ERR or SQLException.UNKNOWN_ERR.
\section3 db.transaction(callback(tx))
-This method creates a read/write transaction and passed to \e callback. In this function,
-you can call \e executeSql on \e tx to read and modify the database.
+This method creates a read/write transaction and passed to \i callback. In this function,
+you can call \i executeSql on \i tx to read and modify the database.
If the callback throws exceptions, the transaction is rolled back.
\section3 db.readTransaction(callback(tx))
-This method creates a read-only transaction and passed to \e callback. In this function,
-you can call \e executeSql on \e tx to read the database (with SELECT statements).
+This method creates a read-only transaction and passed to \i callback. In this function,
+you can call \i executeSql on \i tx to read the database (with SELECT statements).
\section3 results = tx.executeSql(statement, values)
-This method executes a SQL \e statement, binding the list of \e values to SQL positional parameters ("?").
+This method executes a SQL \i statement, binding the list of \i values to SQL positional parameters ("?").
It returns a results object, with the following properties:
\table
\header \o \bold {Type} \o \bold {Property} \o \bold {Value} \o \bold {Applicability}
\row \o int \o rows.length \o The number of rows in the result \o SELECT
-\row \o var \o rows.item(i) \o Function that returns row \e i of the result \o SELECT
+\row \o var \o rows.item(i) \o Function that returns row \i i of the result \o SELECT
\row \o int \o rowsAffected \o The number of rows affected by a modification \o UPDATE, DELETE
\row \o string \o insertId \o The id of the row inserted \o INSERT
\endtable
It is occasionally necessary to run some imperative code at application (or
component instance) startup. While it is tempting to just include the startup
-script as \e {global code} in an external script file, this can have severe limitations
+script as \i {global code} in an external script file, this can have severe limitations
as the QML environment may not have been fully established. For example, some objects
might not have been created or some \l {Property Binding}s may not have been run.
\l {QML JavaScript Restrictions} covers the exact limitations of global script code.
-The QML \l Component element provides an \e attached \c onCompleted property that
+The QML \l Component element provides an \i attached \c onCompleted property that
can be used to trigger the execution of script code at startup after the
QML environment has been completely established. For example:
library itself must be imported to use any of the \l {QML Elements}, as they
are not included in the global namespace by default.)
-The \c Qt module is an \e installed module; it is found in the
+The \c Qt module is an \i installed module; it is found in the
\l{#import-path}{import path}. There are two types of QML modules:
located modules (defined by a URL) and installed modules (defined by a URI).
By default, when a module is imported, its contents are imported into the global namespace. You may choose to import the module into another namespace, either to allow identically-named types to be referenced, or purely for readability.
-To import a module into a specific namespace, use the \e as keyword:
+To import a module into a specific namespace, use the \i as keyword:
\snippet doc/src/snippets/declarative/imports/named-imports.qml imports
The same type can be provided by different files in different versions, in which
case later versions (e.g. 1.2) must precede earlier versions (e.g. 1.0),
-since the \e first name-version match is used and a request for a version of a type
+since the \i first name-version match is used and a request for a version of a type
can be fulfilled by one defined in an earlier version of the module. If a user attempts
to import a version earlier than the earliest provided or later than the latest provided,
the import produces a runtime error, but if the user imports a version within the range of versions provided,
are provided by directories later in the search path).
The versioning system ensures that a given QML file will work regardless of the version
-of installed software, since a versioned import \e only imports types for that version,
+of installed software, since a versioned import \i only imports types for that version,
leaving other identifiers available, even if the actual installed version might otherwise
provide those identifiers.
}
\endqml
-Since a \e relative URL is the same
+Since a \i relative URL is the same
as a relative file, development of QML on regular file systems remains simple:
\qml
\section1 Properties
-QML components have \e properties that can be read and modified by other objects.
+QML components have \i properties that can be read and modified by other objects.
In QML, properties serve many purposes but their main function is to bind to
values. Values may be a \l{QML Basic Types}{basic type}, or other QML elements.
\section1 Types of Properties
-Properties may bind to different types, but they are are \e type-safe. That is,
+Properties may bind to different types, but they are are \i type-safe. That is,
properties only allow you to assign a value that matches the property type. For
example, if a property is a real, and if you try to assign a string to it you
will get an error.
\keyword attached-properties
\section2 Attached Properties
-Certain objects provide additional properties by \e attaching properties to other
-objects. For example, the \l Keys element have properties that can \e attach to other QML
+Certain objects provide additional properties by \i attaching properties to other
+objects. For example, the \l Keys element have properties that can \i attach to other QML
objects to provide keyboard handling.
\snippet doc/src/snippets/declarative/properties.qml list attached property
The element \l ListView provides the delegate, \c listdelegate, the property
\c isCurrentItem as an attached property. The \c ListView.isCurrentItem
-\e{attached property} provides highlight information to the delegate.
+\i{attached property} provides highlight information to the delegate.
Effectively, the \l ListView element attaches the \c ListView.isCurrentItem
property to each delegate it creates.
\keyword attached-signalhandlers
\section2 Attached Signal Handlers
-\e {Attached signal handlers} are similar
+\i {Attached signal handlers} are similar
to \l{Attached Properties}{attached properties} in that they attach to objects
to provide additional functionality to objects. Two prominent elements,
\l Component and \l Keys element provide
\keyword qml-grouped-properties
\section2 Grouped Properties
-In some cases properties form a logical group and use either the \e dot notation
-or \e group notation.
+In some cases properties form a logical group and use either the \i dot notation
+or \i group notation.
Grouped properties may be written both ways:
\snippet doc/src/snippets/declarative/properties.qml grouped properties
Unlike a property definition, which allocates a new, unique storage space for
the property, a property alias connects the newly declared property, called the
-\e{aliasing property} as a direct reference to an existing property, the
-\e{aliased property}. Read or write operations on the aliasing property results
+\i{aliasing property} as a direct reference to an existing property, the
+\i{aliased property}. Read or write operations on the aliasing property results
in a read or write operations on the aliased property, respectively.
A property alias declaration is similar to an ordinary property definition:
\section2 Default Properties
When imported, QML components will bind declared children to their designated
-\e{default properties}. The optional \c default attribute specifies a property
-as the \e {default property}. For example, the State element's default property
+\i{default properties}. The optional \c default attribute specifies a property
+as the \i {default property}. For example, the State element's default property
is its \l{State::changes}{changes} property. \l PropertyChanges elements
may simply be placed as the \c{State}'s children and they will be bound to the
\c changes property.
A QML document always begins with one or more import statements. To prevent elements
introduced in later versions from affecting existing QML programs, the element types
available within a document are controlled by the imported QML \l {Modules}. That is,
-QML is a \e versioned language.
+QML is a \i versioned language.
-Syntactically a QML document is self contained; QML does \e not have a preprocessor that
+Syntactically a QML document is self contained; QML does \i not have a preprocessor that
modifies the document prior to presentation to the QML runtime. \c import statements
do not "include" code in the document, but instead instruct the QML runtime on how to
resolve type references found in the document. Any type reference present in a QML
document - such as \c Rectangle and \c ListView - including those made within an
-\l {Inline JavaScript}{JavaScript block} or \l {Property Binding}s, are \e resolved based exclusively on the
+\l {Inline JavaScript}{JavaScript block} or \l {Property Binding}s, are \i resolved based exclusively on the
import statements. QML does not import any modules by default, so at least one \c import
statement must be present or no elements will be available!
A QML document defines a single, top-level \l {QDeclarativeComponent}{QML component}. A QML component
is a template that is interpreted by the QML runtime to create an object with some predefined
behaviour. As it is a template, a single QML component can be "run" multiple times to
-produce several objects, each of which are said to be \e instances of the component.
+produce several objects, each of which are said to be \i instances of the component.
Once created, instances are not dependent on the component that created them, so they can
operate on independent data. Here is an example of a simple "Button" component (defined
In addition to the top-level component that all QML documents define, and any reusable
components placed in separate files, documents may also
-include \e inline components. Inline components are declared using the
+include \i inline components. Inline components are declared using the
\l Component element, as can be seen in the first example above. Inline components share
all the characteristics of regular top-level components and use the same \c import list as their
containing QML document. Components are one of the most basic building blocks in QML, and are
\section1 Object Identifiers
-Each object can be given a special \e id value that allows the object to be identified
+Each object can be given a special \i id value that allows the object to be identified
and referred to by other objects.
For example, below we have two \l Text objects. The first \l Text object
}
\endqml
-QML properties are what is known as \e type-safe. That is, they only allow you to assign a value that
+QML properties are what is known as \i type-safe. That is, they only allow you to assign a value that
matches the property type. For example, the \c x property of item is a real, and if you try to assign
a string to it you will get an error.
When a property changes value, it can send a signal to notify others of this change.
-To receive these signals, simply create a \e {signal handler} named with an \c on<Property>Changed
+To receive these signals, simply create a \i {signal handler} named with an \c on<Property>Changed
syntax. For example, the \l Rectangle element has \l {Item::}{width} and \l {Rectangle::}{color}
properties. Below, we have a \l Rectangle object that has defined two signal handlers,
\c onWidthChanged and \c onColorChanged, which will automaticallly be called whenever these
\target attached-properties
Some objects attach properties to another object. Attached Properties
-are of the form \e {Type.property} where \e Type is the type of the
-element that attaches \e property.
+are of the form \i {Type.property} where \i Type is the type of the
+element that attaches \i property.
-For example, the \l ListView element attaches the \e ListView.isCurrentItem property
+For example, the \l ListView element attaches the \i ListView.isCurrentItem property
to each delegate it creates:
\qml
}
\endqml
-All signal handlers begin with \e "on".
+All signal handlers begin with \i "on".
Some signal handlers include an optional parameter. For example
the MouseArea \l{MouseArea::}{onPressed} signal handler has a \c mouse parameter
QML items such as ListView, GridView and \l Repeater require Data Models
that provide the data to be displayed.
-These items typically require a \e delegate component that
+These items typically require a \i delegate component that
creates an instance for each item in the model. Models may be static, or
have items modified, inserted, removed or moved dynamically.
Data is provided to the delegate via named data roles which the
-delegate may bind to. Here is a ListModel with two roles, \e type and \e age,
+delegate may bind to. Here is a ListModel with two roles, \i type and \i age,
and a ListView with a delegate that binds to these roles to display their
values:
\snippet doc/src/snippets/declarative/qml-data-models/listmodel-listview.qml document
If there is a naming clash between the model's properties and the delegate's
-properties, the roles can be accessed with the qualified \e model name instead.
-For example, if a \l Text element had \e type or \e age properties, the text in the
-above example would display those property values instead of the \e type and \e age values
+properties, the roles can be accessed with the qualified \i model name instead.
+For example, if a \l Text element had \i type or \i age properties, the text in the
+above example would display those property values instead of the \i type and \i age values
from the model item. In this case, the properties could have been referenced as
\c model.type and \c model.age instead to ensure the delegate displays the
property values from the model item.
-A special \e index role containing the index of the item in the model
+A special \i index role containing the index of the item in the model
is also available to the delegate. Note this index is set to -1 if the item is removed from
the model. If you bind to the index role, be sure that the logic
accounts for the possibility of index being -1, i.e. that the item
attached property.)
Models that do not have named roles (such as the QStringList model shown below)
-will have the data provided via the \e modelData role. The \e modelData role is also provided for
-models that have only one role. In this case the \e modelData role
+will have the data provided via the \i modelData role. The \i modelData role is also provided for
+models that have only one role. In this case the \i modelData role
contains the same data as the named role.
QML provides several types of data models among the built-in set of
\snippet doc/src/snippets/declarative/qml-data-models/listelements.qml model
-The above model has two roles, \e name and \e cost. These can be bound
+The above model has two roles, \i name and \i cost. These can be bound
to by a ListView delegate, for example:
\snippet doc/src/snippets/declarative/qml-data-models/listelements.qml view
\dots
\snippet doc/src/snippets/declarative/qml-data-models/dynamic-listmodel.qml mouse area
-When the MouseArea is clicked, \c fruitModel will have two roles, \e cost and \e name.
+When the MouseArea is clicked, \c fruitModel will have two roles, \i cost and \i name.
Even if subsequent roles are added, only the first two will be handled by views
using the model. To reset the roles available in the model, call ListModel::clear().
XmlListModel allows construction of a model from an XML data source. The roles
are specified via the \l XmlRole element.
-The following model has three roles, \e title, \e link and \e description:
+The following model has three roles, \i title, \i link and \i description:
\qml
XmlListModel {
id: feedModel
\section2 QStringList-based model
-A model may be a simple QStringList, which provides the contents of the list via the \e modelData role.
+A model may be a simple QStringList, which provides the contents of the list via the \i modelData role.
Here is a ListView with a delegate that references its model item's
value using the \c modelData role:
\endtable
Here is an application with a QAbstractListModel subclass named \c AnimalModel
-that has \e type and \e size roles. It calls QAbstractItemModel::setRoleNames() to set the
+that has \i type and \i size roles. It calls QAbstractItemModel::setRoleNames() to set the
role names for accessing the properties via QML:
\snippet examples/declarative/modelviews/abstractitemmodel/model.h 0
\snippet examples/declarative/modelviews/abstractitemmodel/main.cpp 0
\dots
-This model is displayed by a ListView delegate that accesses the \e type and \e size
+This model is displayed by a ListView delegate that accesses the \i type and \i size
roles:
\snippet examples/declarative/modelviews/abstractitemmodel/view.qml 0
with models of type QAbstractItemModel:
\list
-\o \e hasModelChildren role property to determine whether a node has child nodes.
+\o \i hasModelChildren role property to determine whether a node has child nodes.
\o \l VisualDataModel::rootIndex allows the root node to be specifed
\o \l VisualDataModel::modelIndex() returns a QModelIndex which can be assigned to VisualDataModel::rootIndex
\o \l VisualDataModel::parentModelIndex() returns a QModelIndex which can be assigned to VisualDataModel::rootIndex
properties of the object are provided as roles.
The example below creates a list with one item, showing the color of the
-\e myText text. Note the use of the fully qualified \e model.color property
-to avoid clashing with \e color property of the Text element in the delegate.
+\i myText text. Note the use of the fully qualified \i model.color property
+to avoid clashing with \i color property of the Text element in the delegate.
\qml
Rectangle {
be properties of each of the views. Similarly, it might be of interest
to access or show some properties of the model.
-In the following example, the delegate shows the property \e{language}
+In the following example, the delegate shows the property \i{language}
of the model, and the color of one of the fields depends on the
-property \e{fruit_color} of the view.
+property \i{fruit_color} of the view.
\snippet doc/src/snippets/declarative/models/views-models-delegates.qml rectangle
ListView.view.model.setData(index, field, value)
\endjs
-...assuming that \e{field} holds the name of the field which should be
-updated, and that \e{value} holds the new value.
+...assuming that \i{field} holds the name of the field which should be
+updated, and that \i{value} holds the new value.
*/
\section1 Clipping
-\e clip is set to false by default. Enable clipping only when necessary.
+\i clip is set to false by default. Enable clipping only when necessary.
\section1 Anchors vs. Binding
\endlist
However, the above does not mean that you have no use for the network transparency of QML.
-There are many good and useful things you \e can do:
+There are many good and useful things you \i can do:
\list
\i Create \l Image elements with source URLs of any online images. GOOD
\i Use \l{XMLHttpRequest}{XMLHttpRequest} to interact with online services. GOOD
\endlist
-The only reason this page is necessary at all is that JavaScript, when run in a \e{web browser},
+The only reason this page is necessary at all is that JavaScript, when run in a \i{web browser},
has quite many restrictions. With QML, you should neither rely on similar restrictions, nor
worry about working around them.
*/
\o \l AnchorChanges
\endlist
-Many user interface designs are \e state driven; interfaces have configurations
+Many user interface designs are \i state driven; interfaces have configurations
that differ depending on the current state. For example, a traffic signal will
configure its flags or lights depending on its state. While in the signal's
\c stop state, a red light will turn on while the yellow and the green lights
will turn off. In the \c caution state, the yellow light is on while the other
lights are turned off.
-In QML, \e states are a set of property configurations defined in a \l State
+In QML, \i states are a set of property configurations defined in a \l State
element. Different configurations could, for example:
\list
\section1 The Default State
-Every \l Item based component has a \c state property and a \e{default state}.
+Every \l Item based component has a \c state property and a \i{default state}.
The default state is the empty string (\c{""}) and contains all of an item's
initial property values. The default state is useful for managing property
values before state changes. Setting the \c state property to an empty string
parameters are used, the parameter types must be declared, as for the \c string
and \c variant arguments of the \c perform signal.
-Adding a signal to an item automatically adds a \e{signal handler} as well. The
+Adding a signal to an item automatically adds a \i{signal handler} as well. The
signal hander is named \c on<SignalName>, with the first letter of the signal in
uppercase. The previous signals have the following signal handlers:
\snippet doc/src/snippets/declarative/events.qml signal handler declaration
Signal objects have a \c connect() method to a connect a signal either to a
method or another signal. When a signal is connected to a method, the method is
automatically invoked whenever the signal is emitted. (In Qt terminology, the
-method is a \e slot that is connected to the \e signal; all methods defined in
+method is a \i slot that is connected to the \i signal; all methods defined in
QML are created as \l{Signals & Slots}{Qt slots}.) This enables a signal
to be received by a method instead of a \l {Signal Handlers}{signal handler}.
\title Importing Reusable Components
-A \e component is an instantiable QML definition, typically contained in a
-\c .qml file. For instance, a Button \e component may be defined in
+A \i component is an instantiable QML definition, typically contained in a
+\c .qml file. For instance, a Button \i component may be defined in
\c Button.qml. The QML runtime may instantiate this Button component to create
-Button \e objects. Alternatively, a component may be defined inside a
+Button \i objects. Alternatively, a component may be defined inside a
\l Component element.
Moreover, the Button definition may also contain other components. A Button
\keyword qml-top-level
\section1 Top-Level Component
-Choosing the \e{top-level} or the \e{root} object of components is an important
+Choosing the \i{top-level} or the \i{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
\endcode
These expressions can include references to other objects and properties, in which case
-a \e binding is established: when the value of the expression changes, the property the
+a \i binding is established: when the value of the expression changes, the property the
expression has been assigned to is automatically updated to that value.
\code
In the example above, the \c text2 object will display the same text as \c text1. If \c text1 is changed,
\c text2 is automatically changed to the same value.
-Note that to refer to other objects, we use their \e id values. (See below for more
-information on the \e id property.)
+Note that to refer to other objects, we use their \i id values. (See below for more
+information on the \i id property.)
\section1 QML Comments
the development of QML-based applications.
The QML Viewer is a tool for testing and developing QML applications. It is
-\e not intended for use in a production environment and should not be used for the
+\i not intended for use in a production environment and should not be used for the
deployment of QML applications. In those cases, the QML runtime should be invoked
from a Qt application instead; see \l {Qt Declarative UI Runtime} for more
information.
N900 platform and most S60 5.0-based or newer Symbian devices, this property
automatically updates to reflect the device's actual orientation; on other platforms,
this indicates the orientation currently selected in the QML Viewer's
-\e {Settings -> Properties} menu. The \c orientation value can be one of the following:
+\i {Settings -> Properties} menu. The \c orientation value can be one of the following:
\list
\o \c Orientation.Portrait
\keyword qml-view-delegate
\section1 View Delegates
-Views need a \e delegate to visually represent an item in a list. A view will
+Views need a \i delegate to visually represent an item in a list. A view will
visualize each item list according to the template defined by the delegate.
Items in a model are accessible through the \c index property as well as the
item's properties.
\section1 Decorating Views
-Views allow visual customization through \e decoration properties such as the \c header, \c footer, and \c section properties. By binding an object, usually
+Views allow visual customization through \i decoration properties such as the \c header, \c footer, and \c section properties. By binding an object, usually
another visual object, to these properties, the views are decoratable. A footer
may include a \l Rectangle element showcasing borders or a header that displays
a logo on top of the list.
\section1 ListView Sections
-\l {ListView} contents may be grouped into \e sections, where related list items
+\l {ListView} contents may be grouped into \i sections, where related list items
are labeled according to their sections. Further, the sections may be decorated
with \l{qml-view-delegate}{delegates}.
Once this is done, all files specified by relative paths in QML will be loaded from
the resource system instead. Use of the resource system is completely transparent to
the QML layer; this means all QML code should refer to resource files using relative
-paths and should \e not use the \c qrc scheme. This scheme should only be used from
+paths and should \i not use the \c qrc scheme. This scheme should only be used from
C++ code for referring to resource files.
Here is a application packaged using the \l {The Qt Resource System}{Qt resource system}.
int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName);
\endcode
- The former is the standard form which registers the type \e T as a new type.
+ The former is the standard form which registers the type \i T as a new type.
The latter allows a particular revision of a class to be registered in
a specified version (see \l {QML Type Versioning}).
Custom properties can be made available to scripts by registering
them with the script engine. This is most easily done by setting
- properties of the script engine's \e{Global Object}:
+ properties of the script engine's \i{Global Object}:
\snippet doc/src/snippets/qtjavascript/registeringvalues/main.cpp 0
\target qtprogrammers
\title QML for Qt Programmers
-While QML does not require Qt knowledge to use, if you \e are already familiar with Qt,
+While QML does not require Qt knowledge to use, if you \i are already familiar with Qt,
much of your knowledge is directly relevant to learning and using QML. Of course,
an application with a UI defined in QML also uses Qt for all the non-UI logic.
\o Qt models - used directly in data binding (QAbstractItemModel)
\endlist
-Qt knowledge is \e required for \l {Extending QML Functionalities using C++},
+Qt knowledge is \i required for \l {Extending QML Functionalities using C++},
and also for \l{Integrating QML Code with existing Qt UI code}.
\section1 QML Items compared with QWidgets
\section1 The QML Language
QML is a high level, scripted language. Its commands, more correctly
-\e elements, leverage the power and efficiency of the Qt libraries to make easy
+\i elements, leverage the power and efficiency of the Qt libraries to make easy
to use commands that perform intuitive functions. Drawing a rectangle,
displaying an image, and application events -- all are possible with declarative
programming.
\l{About JavaScript}{JavaScript} to implement the high level user interface
logic.
-A QML element usually has various \e properties that help define the element.
+A QML element usually has various \i properties that help define the element.
For example, if we created an element called Circle then the radius of the
circle would be a property. Building user interfaces by importing these elements
is one of the great feature of QML and Qt Quick.
Care must be used when accessing \l {Attached Properties} from bindings due
to their interaction with the scope object. Conceptually attached properties
-exist on \e all objects, even if they only have an effect on a subset of those.
+exist on \i all objects, even if they only have an effect on a subset of those.
Consequently unqualified attached property reads will always resolve to an
attached property on the scope object, which is not always what the programmer
intended.
The \c y property is used to position the text vertically at 30 pixels from the top of its parent.
The \c anchors.horizontalCenter property refers to the horizontal center of an element.
-In this case, we specify that our text element should be horizontally centered in the \e page element (see \l{anchor-layout}{Anchor-Based Layout}).
+In this case, we specify that our text element should be horizontally centered in the \i page element (see \l{anchor-layout}{Anchor-Based Layout}).
The \c font.pointSize and \c font.bold properties are related to fonts and use the \l{dot properties}{dot notation}.
\snippet examples/declarative/tutorials/helloworld/Cell.qml 1
-The root element of our component is an \l Item with the \c id \e container.
+The root element of our component is an \l Item with the \c id \i container.
An \l Item is the most basic visual element in QML and is often used as a container for other elements.
\snippet examples/declarative/tutorials/helloworld/Cell.qml 4
-We declare a \c cellColor property. This property is accessible from \e outside our component, this allows us
+We declare a \c cellColor property. This property is accessible from \i outside our component, this allows us
to instantiate the cells with different colors.
This property is just an alias to an existing property - the color of the rectangle that compose the cell (see \l{Property Binding}).
\snippet examples/declarative/tutorials/helloworld/Cell.qml 5
-We want our component to also have a signal that we call \e clicked with a \e cellColor parameter of type \e color.
+We want our component to also have a signal that we call \i clicked with a \i cellColor parameter of type \i color.
We will use this signal to change the color of the text in the main QML file later.
\snippet examples/declarative/tutorials/helloworld/Cell.qml 2
-Our cell component is basically a colored rectangle with the \c id \e rectangle.
+Our cell component is basically a colored rectangle with the \c id \i rectangle.
The \c anchors.fill property is a convenient way to set the size of an element.
In this case the rectangle will have the same size as its parent (see \l{anchor-layout}{Anchor-Based Layout}).
In order to change the color of the text when clicking on a cell, we create a \l MouseArea element with
the same size as its parent.
-A \l MouseArea defines a signal called \e clicked.
-When this signal is triggered we want to emit our own \e clicked signal with the color as parameter.
+A \l MouseArea defines a signal called \i clicked.
+When this signal is triggered we want to emit our own \i clicked signal with the color as parameter.
\section2 The main QML file
\snippet examples/declarative/tutorials/helloworld/tutorial2.qml 1
-When the \e clicked signal of our cell is triggered, we want to set the color of the text to the \e cellColor passed as a parameter.
-We can react to any signal of our component through a property of the name \e 'onSignalName' (see \l{Signal Handlers}).
+When the \i clicked signal of our cell is triggered, we want to set the color of the text to the \i cellColor passed as a parameter.
+We can react to any signal of our component through a property of the name \i 'onSignalName' (see \l{Signal Handlers}).
*/
/*!
\snippet examples/declarative/tutorials/helloworld/tutorial3.qml 2
-First, we create a new \e down state for our text element.
+First, we create a new \i down state for our text element.
This state will be activated when the \l MouseArea is pressed, and deactivated when it is released.
-The \e down state includes a set of property changes from our implicit \e {default state}
+The \i down state includes a set of property changes from our implicit \i {default state}
(the items as they were initially defined in the QML).
Specifically, we set the \c y property of the text to \c 160, the rotation to \c 180 and the \c color to red.
we add a transition between our two states.
\c from and \c to define the states between which the transition will run.
-In this case, we want a transition from the default state to our \e down state.
+In this case, we want a transition from the default state to our \i down state.
-Because we want the same transition to be run in reverse when changing back from the \e down state to the default state,
+Because we want the same transition to be run in reverse when changing back from the \i down state to the default state,
we set \c reversible to \c true.
This is equivalent to writing the two transitions separately.
You can still ignore these events in the handler to let them pass through.
The Binding element can now be used as a value source, and will also restore any previously
-set binding when its \e when clause becomes false.
+set binding when its \i when clause becomes false.
Flickable: added dragging, draggingHorizontally and draggingVerically properties.
Added topMargin, bottomMargin, leftMargin, rightMargin, xOrigin, yOrigin properties.