qiurui
/
qtdeclarative
mirror of https://github.com/qt/qtdeclarative.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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 2022-08-11 09:16:17 +02:00
parent f2c87dda91
commit 2bd4ee37ff
1 changed files with 238 additions and 229 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

423
src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc
View File

@ -19,131 +19,150 @@ 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 \code
[singleton] <TypeName> <InitialVersion> <File> module <ModuleIdentifier>
\endcode \endcode
\li Declares a \l{qtqml-typesystem-objecttypes.html}{QML object type}
to be made available by the module. Declares the module identifier of the module. The <ModuleIdentifier> is the
\list (dotted URI notation) identifier for the module, which must match the module's
install path.
The \l{Identified Modules#Semantics of Identified Modules}
{module identifier directive} must be the first line of the file. Exactly one
module identifier directive may exist in the \c qmldir file.
Example:
\code
module ExampleModule
\endcode
\section2 Object Type Declaration
\code
[singleton] <TypeName> <InitialVersion> <File>
\endcode
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 [singleton] Optional. Used to declare a singleton type.
\li \c <TypeName> is the type being made available \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 <InitialVersion> is the module version for which the type is to be
\li \c <File> is the (relative) file name of the QML file that defines the type made available
\endlist \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 Zero or more object type declarations may exist in the \c qmldir
file, however each object type must have a unique type name within file. However, each object type must have a unique type name within
any particular version of the module. any particular version of the module.
\note To declare a \c singleton type, the QML file defining the \note To declare a \c singleton type, the QML file defining the
type must include the \c {pragma Singleton} statement. type must include the \c {pragma Singleton} statement.
Example: Example:
\code \code
//Style.qml with custom singleton type definition //Style.qml with custom singleton type definition
pragma Singleton pragma Singleton
import QtQuick 2.0 import QtQuick 2.0
QtObject { QtObject {
property int textSize: 20 property int textSize: 20
property color textColor: "green" property color textColor: "green"
} }
// qmldir declaring the singleton type // qmldir declaring the singleton type
module CustomStyles module CustomStyles
singleton Style 1.0 Style.qml singleton Style 1.0 Style.qml
// singleton type in use // singleton type in use
import QtQuick 2.0 import QtQuick 2.0
import CustomStyles 1.0 import CustomStyles 1.0
Text { Text {
font.pixelSize: Style.textSize font.pixelSize: Style.textSize
color: Style.textColor color: Style.textColor
text: "Hello World" text: "Hello World"
} }
\endcode \endcode
\row \section2 Internal Object Type Declaration
\li
\code
internal <TypeName> <File>
\endcode
\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 \code
\c qmldir file. internal <TypeName> <File>
\endcode
Example: Declares an object type that is in the module but should not be
\code made available to users of the module.
internal MyPrivateType MyPrivateType.qml
\endcode
This is necessary if the module may be imported remotely (see Zero or more internal object type declarations may exist in the
\l{Identified Modules#Remotely Installed Identified Modules} \c qmldir file.
{Remotely Installed Identified Modules}) because if an exported type depends
on an non-exported type within the module, the engine must also
load the non-exported type.
\row Example:
\li \code
\code internal MyPrivateType MyPrivateType.qml
<ResourceIdentifier> <InitialVersion> <File> \endcode
\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 This is necessary if the module is imported remotely
\c qmldir file, however each JavaScript resource must have a unique (see \l{Identified Modules#Remotely Installed Identified Modules}
identifier within any particular version of the module. {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
MyScript 1.0 MyScript.js
\endcode
See the documentation about \l{qtqml-javascript-resources.html} \code
{defining JavaScript resources} and <ResourceIdentifier> <InitialVersion> <File>
\l{qtqml-javascript-imports.html} \endcode
{Importing JavaScript Resources In QML} for more 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.
[optional] plugin <Name> [<Path>]
\endcode
\li Declares a plugin to be made available by the module.
\list Zero or more JavaScript resource declarations may exist in the
\c qmldir file. However, each JavaScript resource must have a unique
identifier within any particular version of the module.
Example:
\code
MyScript 1.0 MyScript.js
\endcode
See the documentation about \l{qtqml-javascript-resources.html}
{defining JavaScript resources} and
\l{qtqml-javascript-imports.html}
{Importing JavaScript Resources In QML} for more information.
\section2 Plugin Declaration
\code
[optional] plugin <Name> [<Path>]
\endcode
Declares a plugin to be made available by the module.
\list
\li \c optional denotes that the plugin itself does not contain \li \c optional denotes that the plugin itself does not contain
any relevant code and only serves to load a library it links any relevant code and only serves to load a library it links
to. If given, and if any types for the module are already to. If given, and if any types for the module are already
@ -151,7 +170,7 @@ MyScript 1.0 MyScript.js
other means, QML will not load the plugin. other means, QML will not load the plugin.
\li \c <Name> is the plugin library name. This is usually not the \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 same as the file name of the plugin binary, which is platform
dependent; e.g. the library \c MyAppTypes would produce dependent. For example, the library \c MyAppTypes would produce
\c libMyAppTypes.so on Linux and \c MyAppTypes.dll on Windows. \c libMyAppTypes.so on Linux and \c MyAppTypes.dll on Windows.
\li \c <Path> (optional) specifies either: \li \c <Path> (optional) specifies either:
\list \list
@ -160,137 +179,127 @@ MyScript 1.0 MyScript.js
\li a relative path from the directory containing the \c qmldir \li a relative path from the directory containing the \c qmldir
file to the directory containing the plugin file. file to the directory containing the plugin file.
\endlist \endlist
\endlist
By default the engine searches for the plugin library in the By default, the engine searches for the plugin library in the
directory that contains the \c qmldir file. (The plugin search directory that contains the \c qmldir file. (The plugin search
path can be queried with QQmlEngine::pluginPathList() and path can be queried with QQmlEngine::pluginPathList() and
modified using QQmlEngine::addPluginPath().) modified using QQmlEngine::addPluginPath().)
\endlist
Zero or more C++ plugin declarations may exist in the \c qmldir Zero or more C++ plugin declarations may exist in the \c qmldir
file, however since plugin loading is a relatively expensive file. However, since plugin loading is a relatively expensive
operation, clients are advised to specify at most a single plugin. operation, clients are advised to specify at most a single plugin.
Example: Example:
\code \code
plugin MyPluginLibrary plugin MyPluginLibrary
\endcode \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 \section2 Plugin Classname Declaration
on a C++ plugin for additional functionality. Qt Quick applications
built with static linking cannot resolve the module imports without
this information.
\row \code
\li classname <C++ plugin class>
\code \endcode
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: Provides the class name of the C++ plugin used by the module.
\code
typeinfo mymodule.qmltypes
\endcode
Without such a file, QML tools may be unable to offer features such This information is required for all the QML modules that depend
as code completion for the types defined in your plugins. on a C++ plugin for additional functionality. Qt Quick applications
built with static linking cannot resolve the module imports without
this information.
\row \section2 Type Description File Declaration
\li
\code
depends <ModuleIdentifier> <InitialVersion>
\endcode
\li Declares that this module depends on another.
Example: \code
\code typeinfo <File>
depends MyOtherModule 1.0 \endcode
\endcode
This declaration is necessary only in cases when the dependency is Declares a \l{Type Description Files}{type description file} for
hidden: for example, when the C++ code for one module is used to the module that can be read by QML tools such as Qt Creator to
load QML (perhaps conditionally) which then depends on other access information about the types defined by the module's plugins.
modules. In such cases, the \c depends declaration is necessary \c <File> is the (relative) file name of a \c .qmltypes file.
to include the other modules in application packages.
\row
\li
\code
import <ModuleIdentifier> [<Version>]
\endcode
\li Declares that this module imports another.
Example: Example:
\code \code
import MyOtherModule 1.0 typeinfo mymodule.qmltypes
\endcode \endcode
The types from the other module are made available in the same type Without such a file, QML tools may be unable to offer features such
namespace as this module is imported into. Omitting the version as code completion for the types defined in your plugins.
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.
\row \section2 Module Dependencies Declaration
\li
\code
# <Comment>
\endcode
\li Declares a comment. These are ignored by the engine.
Example: \code
\code depends <ModuleIdentifier> <InitialVersion>
# this is a comment \endcode
\endcode
\row Declares that this module depends on another.
\li
\code
designersupported
\endcode
\li Set this property if the plugin is supported by Qt Quick Designer. Example:
By default, the plugin will not be supported. \code
depends MyOtherModule 1.0
\endcode
A plugin that is supported by Qt Quick Designer has to be properly This declaration is necessary only in cases when the dependency is
tested. This means that the plugin does not crash when running inside hidden: for example, when the C++ code for one module is used to
the qml2puppet that is used by Qt Quick Designer to execute QML. load QML (perhaps conditionally), which then depends on other
Generally the plugin should work well in the Qt Quick Designer modules. In such cases, the \c depends declaration is necessary
and not cause any show stoppers, like taking huge amounts of memory, to include the other modules in application packages.
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, \section2 Module Import Declaration
but they are still available as empty boxes and the properties can be edited.
\row \code
\li import <ModuleIdentifier> [<Version>]
\code \endcode
prefer <Path>
\endcode
\li This property directs the QML engine to load any further files for this Declares that this module imports another.
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 Example:
path \c{:/my/path/MyModule/}. Then, add \c{prefer :/my/path/MyModule} to \code
the qmldir file in order to use the files in the resource system, rather import MyOtherModule 1.0
than the ones in the file system. If you then use qmlcachegen for those, \endcode
the pre-compiled files will be available to any clients of the module.
\endtable 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.
Each command in a \c qmldir file must be on a separate line. \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