Doc: Split qmldir entries table into subsections
There are two main problems with the existing table: * The user has to scroll horizontally to view all the content in the right column. * It is difficult to link to the individual entries. Splitting the column into subsections solves these issues. In addition, add a list of all the commands in the qmldir file to get a quick overview of the subsections that follow. Also, make small grammatical fixes to the text. Fixes: QTBUG-105239 Pick-to: 6.4 6.3 6.2 5.15 Change-Id: Ic33caedf317ae1d33ecc606cffc5d664490e242c Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
This commit is contained in:
Andreas Eliasson
parent
f2c87dda91
commit
2bd4ee37ff
|
|
@ -19,278 +19,287 @@ module. For more information about the first form of \c qmldir file, see
|
||||||
|
|
||||||
\section1 Contents of a Module Definition qmldir File
|
\section1 Contents of a Module Definition qmldir File
|
||||||
|
|
||||||
A \c qmldir file is a plain-text file that contains
|
A \c qmldir file is a plain-text file that contains the following commands:
|
||||||
the following commands:
|
|
||||||
|
|
||||||
\table 70%
|
\list
|
||||||
\header
|
\li \l {Module Identifier Declaration}
|
||||||
\li Syntax
|
\li \l {Object Type Declaration}
|
||||||
\li Usage
|
\li \l {Internal Object Type Declaration}
|
||||||
\row
|
\li \l {JavaScript Resource Declaration}
|
||||||
\li
|
\li \l {Plugin Declaration}
|
||||||
\code
|
\li \l {Plugin Classname Declaration}
|
||||||
module <ModuleIdentifier>
|
\li \l {Type Description File Declaration}
|
||||||
\endcode
|
\li \l {Module Dependencies Declaration}
|
||||||
\li Declares the module identifier of the module.
|
\li \l {Module Import Declaration}
|
||||||
The <ModuleIdentifier> is the (dotted URI notation) identifier
|
\li \l {Designer Support Declaration}
|
||||||
for the module, which must match the module's install path.
|
\li \l {Preferred Path Declaration}
|
||||||
|
\endlist
|
||||||
|
|
||||||
The \l{Identified Modules#Semantics of Identified Modules}
|
\note Each command in a \c qmldir file must be on a separate line.
|
||||||
{module identifier directive} must be the first line of the file.
|
|
||||||
Exactly one module identifier directive may exist in the \c qmldir
|
|
||||||
file.
|
|
||||||
|
|
||||||
Example:
|
In addition to commands, you can also add comments, which are lines starting
|
||||||
\code
|
with \c {#}.
|
||||||
module ExampleModule
|
|
||||||
\endcode
|
|
||||||
|
|
||||||
\row
|
\section2 Module Identifier Declaration
|
||||||
\li
|
|
||||||
\code
|
|
||||||
[singleton] <TypeName> <InitialVersion> <File>
|
|
||||||
\endcode
|
|
||||||
\li Declares a \l{qtqml-typesystem-objecttypes.html}{QML object type}
|
|
||||||
to be made available by the module.
|
|
||||||
\list
|
|
||||||
\li \c [singleton] Optional. Used to declare a singleton type.
|
|
||||||
\li \c <TypeName> is the type being made available
|
|
||||||
\li \c <InitialVersion> is the module version for which the type is to be made available
|
|
||||||
\li \c <File> is the (relative) file name of the QML file that defines the type
|
|
||||||
\endlist
|
|
||||||
|
|
||||||
Zero or more object type declarations may exist in the \c qmldir
|
\code
|
||||||
file, however each object type must have a unique type name within
|
module <ModuleIdentifier>
|
||||||
any particular version of the module.
|
\endcode
|
||||||
\note To declare a \c singleton type, the QML file defining the
|
|
||||||
type must include the \c {pragma Singleton} statement.
|
|
||||||
|
|
||||||
Example:
|
Declares the module identifier of the module. The <ModuleIdentifier> is the
|
||||||
\code
|
(dotted URI notation) identifier for the module, which must match the module's
|
||||||
//Style.qml with custom singleton type definition
|
install path.
|
||||||
pragma Singleton
|
|
||||||
import QtQuick 2.0
|
|
||||||
|
|
||||||
QtObject {
|
The \l{Identified Modules#Semantics of Identified Modules}
|
||||||
property int textSize: 20
|
{module identifier directive} must be the first line of the file. Exactly one
|
||||||
property color textColor: "green"
|
module identifier directive may exist in the \c qmldir file.
|
||||||
}
|
|
||||||
|
|
||||||
// qmldir declaring the singleton type
|
Example:
|
||||||
module CustomStyles
|
\code
|
||||||
singleton Style 1.0 Style.qml
|
module ExampleModule
|
||||||
|
\endcode
|
||||||
|
|
||||||
// singleton type in use
|
\section2 Object Type Declaration
|
||||||
import QtQuick 2.0
|
\code
|
||||||
import CustomStyles 1.0
|
[singleton] <TypeName> <InitialVersion> <File>
|
||||||
|
\endcode
|
||||||
|
|
||||||
Text {
|
Declares a \l{qtqml-typesystem-objecttypes.html}{QML object type}
|
||||||
font.pixelSize: Style.textSize
|
to be made available by the module.
|
||||||
color: Style.textColor
|
\list
|
||||||
text: "Hello World"
|
\li \c [singleton] Optional. Used to declare a singleton type.
|
||||||
}
|
\li \c <TypeName> is the type being made available
|
||||||
\endcode
|
\li \c <InitialVersion> is the module version for which the type is to be
|
||||||
|
made available
|
||||||
|
\li \c <File> is the (relative) file name of the QML file that defines
|
||||||
|
the type
|
||||||
|
\endlist
|
||||||
|
|
||||||
\row
|
Zero or more object type declarations may exist in the \c qmldir
|
||||||
\li
|
file. However, each object type must have a unique type name within
|
||||||
\code
|
any particular version of the module.
|
||||||
internal <TypeName> <File>
|
\note To declare a \c singleton type, the QML file defining the
|
||||||
\endcode
|
type must include the \c {pragma Singleton} statement.
|
||||||
\li Declares an object type that is in the module but should not be
|
|
||||||
made available to users of the module.
|
|
||||||
|
|
||||||
Zero or more internal object type declarations may exist in the
|
Example:
|
||||||
\c qmldir file.
|
\code
|
||||||
|
//Style.qml with custom singleton type definition
|
||||||
|
pragma Singleton
|
||||||
|
import QtQuick 2.0
|
||||||
|
|
||||||
Example:
|
QtObject {
|
||||||
\code
|
property int textSize: 20
|
||||||
internal MyPrivateType MyPrivateType.qml
|
property color textColor: "green"
|
||||||
\endcode
|
}
|
||||||
|
|
||||||
This is necessary if the module may be imported remotely (see
|
// qmldir declaring the singleton type
|
||||||
\l{Identified Modules#Remotely Installed Identified Modules}
|
module CustomStyles
|
||||||
{Remotely Installed Identified Modules}) because if an exported type depends
|
singleton Style 1.0 Style.qml
|
||||||
on an non-exported type within the module, the engine must also
|
|
||||||
load the non-exported type.
|
|
||||||
|
|
||||||
\row
|
// singleton type in use
|
||||||
\li
|
import QtQuick 2.0
|
||||||
\code
|
import CustomStyles 1.0
|
||||||
<ResourceIdentifier> <InitialVersion> <File>
|
|
||||||
\endcode
|
|
||||||
\li Declares a JavaScript file to be made available by the module.
|
|
||||||
The resource will be made available via the specified identifier
|
|
||||||
with the specified version number.
|
|
||||||
|
|
||||||
Zero or more JavaScript resource declarations may exist in the
|
Text {
|
||||||
\c qmldir file, however each JavaScript resource must have a unique
|
font.pixelSize: Style.textSize
|
||||||
identifier within any particular version of the module.
|
color: Style.textColor
|
||||||
|
text: "Hello World"
|
||||||
|
}
|
||||||
|
\endcode
|
||||||
|
|
||||||
Example:
|
\section2 Internal Object Type Declaration
|
||||||
\code
|
|
||||||
MyScript 1.0 MyScript.js
|
|
||||||
\endcode
|
|
||||||
|
|
||||||
See the documentation about \l{qtqml-javascript-resources.html}
|
\code
|
||||||
{defining JavaScript resources} and
|
internal <TypeName> <File>
|
||||||
\l{qtqml-javascript-imports.html}
|
\endcode
|
||||||
{Importing JavaScript Resources In QML} for more information.
|
|
||||||
|
|
||||||
\row
|
Declares an object type that is in the module but should not be
|
||||||
\li
|
made available to users of the module.
|
||||||
\code
|
|
||||||
[optional] plugin <Name> [<Path>]
|
|
||||||
\endcode
|
|
||||||
\li Declares a plugin to be made available by the module.
|
|
||||||
|
|
||||||
\list
|
Zero or more internal object type declarations may exist in the
|
||||||
\li \c optional denotes that the plugin itself does not contain
|
\c qmldir file.
|
||||||
any relevant code and only serves to load a library it links
|
|
||||||
to. If given, and if any types for the module are already
|
|
||||||
available, indicating that the library has been loaded by some
|
|
||||||
other means, QML will not load the plugin.
|
|
||||||
\li \c <Name> is the plugin library name. This is usually not the
|
|
||||||
same as the file name of the plugin binary, which is platform
|
|
||||||
dependent; e.g. the library \c MyAppTypes would produce
|
|
||||||
\c libMyAppTypes.so on Linux and \c MyAppTypes.dll on Windows.
|
|
||||||
\li \c <Path> (optional) specifies either:
|
|
||||||
\list
|
|
||||||
\li an absolute path to the directory containing the plugin
|
|
||||||
file, or
|
|
||||||
\li a relative path from the directory containing the \c qmldir
|
|
||||||
file to the directory containing the plugin file.
|
|
||||||
\endlist
|
|
||||||
|
|
||||||
By default the engine searches for the plugin library in the
|
Example:
|
||||||
directory that contains the \c qmldir file. (The plugin search
|
\code
|
||||||
path can be queried with QQmlEngine::pluginPathList() and
|
internal MyPrivateType MyPrivateType.qml
|
||||||
modified using QQmlEngine::addPluginPath().)
|
\endcode
|
||||||
\endlist
|
|
||||||
|
|
||||||
Zero or more C++ plugin declarations may exist in the \c qmldir
|
This is necessary if the module is imported remotely
|
||||||
file, however since plugin loading is a relatively expensive
|
(see \l{Identified Modules#Remotely Installed Identified Modules}
|
||||||
operation, clients are advised to specify at most a single plugin.
|
{Remotely Installed Identified Modules}) because if an exported type depends
|
||||||
|
on a non-exported type within the module, the engine must also
|
||||||
|
load the non-exported type.
|
||||||
|
|
||||||
Example:
|
\section2 JavaScript Resource Declaration
|
||||||
\code
|
|
||||||
plugin MyPluginLibrary
|
|
||||||
\endcode
|
|
||||||
\row
|
|
||||||
\li
|
|
||||||
\code
|
|
||||||
classname <C++ plugin class>
|
|
||||||
\endcode
|
|
||||||
\li Provides the class name of the C++ plugin used by the module.
|
|
||||||
|
|
||||||
This information is required for all the QML modules that depend
|
\code
|
||||||
on a C++ plugin for additional functionality. Qt Quick applications
|
<ResourceIdentifier> <InitialVersion> <File>
|
||||||
built with static linking cannot resolve the module imports without
|
\endcode
|
||||||
this information.
|
|
||||||
|
|
||||||
\row
|
Declares a JavaScript file to be made available by the module.
|
||||||
\li
|
The resource will be made available via the specified identifier
|
||||||
\code
|
with the specified version number.
|
||||||
typeinfo <File>
|
|
||||||
\endcode
|
|
||||||
\li Declares a \l{Type Description Files}{type description file} for
|
|
||||||
the module that can be read by QML tools such as Qt Creator to
|
|
||||||
access information about the types defined by the module's plugins.
|
|
||||||
\c <File> is the (relative) file name of a \c .qmltypes file.
|
|
||||||
|
|
||||||
Example:
|
Zero or more JavaScript resource declarations may exist in the
|
||||||
\code
|
\c qmldir file. However, each JavaScript resource must have a unique
|
||||||
typeinfo mymodule.qmltypes
|
identifier within any particular version of the module.
|
||||||
\endcode
|
|
||||||
|
|
||||||
Without such a file, QML tools may be unable to offer features such
|
Example:
|
||||||
as code completion for the types defined in your plugins.
|
\code
|
||||||
|
MyScript 1.0 MyScript.js
|
||||||
|
\endcode
|
||||||
|
|
||||||
\row
|
See the documentation about \l{qtqml-javascript-resources.html}
|
||||||
\li
|
{defining JavaScript resources} and
|
||||||
\code
|
\l{qtqml-javascript-imports.html}
|
||||||
depends <ModuleIdentifier> <InitialVersion>
|
{Importing JavaScript Resources In QML} for more information.
|
||||||
\endcode
|
|
||||||
\li Declares that this module depends on another.
|
|
||||||
|
|
||||||
Example:
|
\section2 Plugin Declaration
|
||||||
\code
|
|
||||||
depends MyOtherModule 1.0
|
|
||||||
\endcode
|
|
||||||
|
|
||||||
This declaration is necessary only in cases when the dependency is
|
\code
|
||||||
hidden: for example, when the C++ code for one module is used to
|
[optional] plugin <Name> [<Path>]
|
||||||
load QML (perhaps conditionally) which then depends on other
|
\endcode
|
||||||
modules. In such cases, the \c depends declaration is necessary
|
|
||||||
to include the other modules in application packages.
|
|
||||||
\row
|
|
||||||
\li
|
|
||||||
\code
|
|
||||||
import <ModuleIdentifier> [<Version>]
|
|
||||||
\endcode
|
|
||||||
\li Declares that this module imports another.
|
|
||||||
|
|
||||||
Example:
|
Declares a plugin to be made available by the module.
|
||||||
\code
|
|
||||||
import MyOtherModule 1.0
|
|
||||||
\endcode
|
|
||||||
|
|
||||||
The types from the other module are made available in the same type
|
\list
|
||||||
namespace as this module is imported into. Omitting the version
|
\li \c optional denotes that the plugin itself does not contain
|
||||||
imports the latest version available of the other module, specifying
|
any relevant code and only serves to load a library it links
|
||||||
\c auto as version imports the same version as the version of this
|
to. If given, and if any types for the module are already
|
||||||
module specified in the QML \c import statement.
|
available, indicating that the library has been loaded by some
|
||||||
|
other means, QML will not load the plugin.
|
||||||
|
\li \c <Name> is the plugin library name. This is usually not the
|
||||||
|
same as the file name of the plugin binary, which is platform
|
||||||
|
dependent. For example, the library \c MyAppTypes would produce
|
||||||
|
\c libMyAppTypes.so on Linux and \c MyAppTypes.dll on Windows.
|
||||||
|
\li \c <Path> (optional) specifies either:
|
||||||
|
\list
|
||||||
|
\li an absolute path to the directory containing the plugin
|
||||||
|
file, or
|
||||||
|
\li a relative path from the directory containing the \c qmldir
|
||||||
|
file to the directory containing the plugin file.
|
||||||
|
\endlist
|
||||||
|
\endlist
|
||||||
|
|
||||||
\row
|
By default, the engine searches for the plugin library in the
|
||||||
\li
|
directory that contains the \c qmldir file. (The plugin search
|
||||||
\code
|
path can be queried with QQmlEngine::pluginPathList() and
|
||||||
# <Comment>
|
modified using QQmlEngine::addPluginPath().)
|
||||||
\endcode
|
|
||||||
\li Declares a comment. These are ignored by the engine.
|
|
||||||
|
|
||||||
Example:
|
Zero or more C++ plugin declarations may exist in the \c qmldir
|
||||||
\code
|
file. However, since plugin loading is a relatively expensive
|
||||||
# this is a comment
|
operation, clients are advised to specify at most a single plugin.
|
||||||
\endcode
|
|
||||||
|
|
||||||
\row
|
Example:
|
||||||
\li
|
\code
|
||||||
\code
|
plugin MyPluginLibrary
|
||||||
designersupported
|
\endcode
|
||||||
\endcode
|
|
||||||
|
|
||||||
\li Set this property if the plugin is supported by Qt Quick Designer.
|
\section2 Plugin Classname Declaration
|
||||||
By default, the plugin will not be supported.
|
|
||||||
|
|
||||||
A plugin that is supported by Qt Quick Designer has to be properly
|
\code
|
||||||
tested. This means that the plugin does not crash when running inside
|
classname <C++ plugin class>
|
||||||
the qml2puppet that is used by Qt Quick Designer to execute QML.
|
\endcode
|
||||||
Generally the plugin should work well in the Qt Quick Designer
|
|
||||||
and not cause any show stoppers, like taking huge amounts of memory,
|
|
||||||
slowing down the qml2puppet heavily or anything else that renders
|
|
||||||
the plugin effectively unusable in the Qt Quick Designer.
|
|
||||||
|
|
||||||
The items of an unsupported plugin are not painted in the Qt Quick Designer,
|
Provides the class name of the C++ plugin used by the module.
|
||||||
but they are still available as empty boxes and the properties can be edited.
|
|
||||||
|
|
||||||
\row
|
This information is required for all the QML modules that depend
|
||||||
\li
|
on a C++ plugin for additional functionality. Qt Quick applications
|
||||||
\code
|
built with static linking cannot resolve the module imports without
|
||||||
prefer <Path>
|
this information.
|
||||||
\endcode
|
|
||||||
|
|
||||||
\li This property directs the QML engine to load any further files for this
|
\section2 Type Description File Declaration
|
||||||
module from <path>, rather than the current directory. This can be used
|
|
||||||
to load files compiled with qmlcachegen.
|
|
||||||
|
|
||||||
For example, you can add a module's QML files as resources to a resource
|
\code
|
||||||
path \c{:/my/path/MyModule/}. Then, add \c{prefer :/my/path/MyModule} to
|
typeinfo <File>
|
||||||
the qmldir file in order to use the files in the resource system, rather
|
\endcode
|
||||||
than the ones in the file system. If you then use qmlcachegen for those,
|
|
||||||
the pre-compiled files will be available to any clients of the module.
|
|
||||||
|
|
||||||
\endtable
|
Declares a \l{Type Description Files}{type description file} for
|
||||||
|
the module that can be read by QML tools such as Qt Creator to
|
||||||
|
access information about the types defined by the module's plugins.
|
||||||
|
\c <File> is the (relative) file name of a \c .qmltypes file.
|
||||||
|
|
||||||
Each command in a \c qmldir file must be on a separate line.
|
Example:
|
||||||
|
\code
|
||||||
|
typeinfo mymodule.qmltypes
|
||||||
|
\endcode
|
||||||
|
|
||||||
|
Without such a file, QML tools may be unable to offer features such
|
||||||
|
as code completion for the types defined in your plugins.
|
||||||
|
|
||||||
|
\section2 Module Dependencies Declaration
|
||||||
|
|
||||||
|
\code
|
||||||
|
depends <ModuleIdentifier> <InitialVersion>
|
||||||
|
\endcode
|
||||||
|
|
||||||
|
Declares that this module depends on another.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
\code
|
||||||
|
depends MyOtherModule 1.0
|
||||||
|
\endcode
|
||||||
|
|
||||||
|
This declaration is necessary only in cases when the dependency is
|
||||||
|
hidden: for example, when the C++ code for one module is used to
|
||||||
|
load QML (perhaps conditionally), which then depends on other
|
||||||
|
modules. In such cases, the \c depends declaration is necessary
|
||||||
|
to include the other modules in application packages.
|
||||||
|
|
||||||
|
\section2 Module Import Declaration
|
||||||
|
|
||||||
|
\code
|
||||||
|
import <ModuleIdentifier> [<Version>]
|
||||||
|
\endcode
|
||||||
|
|
||||||
|
Declares that this module imports another.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
\code
|
||||||
|
import MyOtherModule 1.0
|
||||||
|
\endcode
|
||||||
|
|
||||||
|
The types from the other module are made available in the same type
|
||||||
|
namespace as this module is imported into. Omitting the version
|
||||||
|
imports the latest version available of the other module. Specifying
|
||||||
|
\c auto as version imports the same version as the version of this
|
||||||
|
module specified in the QML \c import statement.
|
||||||
|
|
||||||
|
\section2 Designer Support Declaration
|
||||||
|
|
||||||
|
\code
|
||||||
|
designersupported
|
||||||
|
\endcode
|
||||||
|
|
||||||
|
Set this property if the plugin is supported by Qt Quick Designer.
|
||||||
|
By default, the plugin will not be supported.
|
||||||
|
|
||||||
|
A plugin that is supported by Qt Quick Designer has to be properly
|
||||||
|
tested. This means that the plugin does not crash when running inside
|
||||||
|
the qml2puppet that is used by Qt Quick Designer to execute QML.
|
||||||
|
Generally, the plugin should work well in the Qt Quick Designer
|
||||||
|
and not cause any show stoppers, like taking excessive amounts of memory,
|
||||||
|
slowing down the qml2puppet heavily, or anything else that renders
|
||||||
|
the plugin effectively unusable in the Qt Quick Designer.
|
||||||
|
|
||||||
|
The items of an unsupported plugin are not painted in the Qt Quick Designer,
|
||||||
|
but they are still available as empty boxes and the properties can be edited.
|
||||||
|
|
||||||
|
\section2 Preferred Path Declaration
|
||||||
|
|
||||||
|
\code
|
||||||
|
prefer <Path>
|
||||||
|
\endcode
|
||||||
|
|
||||||
|
This property directs the QML engine to load any further files for this
|
||||||
|
module from <path>, rather than the current directory. This can be used
|
||||||
|
to load files compiled with qmlcachegen.
|
||||||
|
|
||||||
|
For example, you can add a module's QML files as resources to a resource
|
||||||
|
path \c{:/my/path/MyModule/}. Then, add \c{prefer :/my/path/MyModule} to
|
||||||
|
the qmldir file in order to use the files in the resource system, rather
|
||||||
|
than the ones in the file system. If you then use qmlcachegen for those,
|
||||||
|
the pre-compiled files will be available to any clients of the module.
|
||||||
|
|
||||||
\section1 Versioning Semantics
|
\section1 Versioning Semantics
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue