1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
/****************************************************************************
**
** Copyright (C) 2022 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Installer Framework.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example treename
\ingroup qtifwexamples
\title Tree Name Example
\brief Using components' package.xml files to define custom locations in the component tree.
\image qtifw-examples-treename.png
\e{Tree Name} illustrates how to specify custom locations for components in
the component tree view and how that influences the installation and
maintenance processes.
\include installerfw-examples-configuring.qdocinc
\list
\li The \c <WizardShowPageList> element is set to \c false to hide the page
list widget on the left side of the installer wizard window.
\endlist
\quotefile treename/config/config.xml
\include installerfw-examples-packaging.qdocinc
\list
\li The \c <TreeName> element specifies the location of the component in the
component tree. The element accepts an optional \c moveChildren attribute
with a boolean value. If the value is set to \c true, any child components
of this component are also moved to the modified location.
\note Without this element the identifier of this component decides the location
in the component tree.
\endlist
In this example, the package.xml files for the components contain additional
elements that specify the component tree locations. The following sections illustrate
how the elements are used.
\section1 Specifying Tree Name to Root Node
We define a tree name \e ASub1ToRoot for component \e{A subcomponent 1}.
Thus, this child component of \e A becomes a new root component.
By default the children are not moved to the new location, so
\e {A sub-subcomponent1} becomes a new direct child of \e A.
\quotefile treename/packages/A.sub1/meta/package.xml
\section1 Specifying Tree Name and Moving Children
As above, we define a tree name \e BSub1ToRoot for component \e{B subcomponent 1}, but
this time we set the \c moveChildren attribute to \c true. The component becomes a new
root component and the child component \e {B sub-subcomponent 1} of this
component moves to the new location with the parent.
\quotefile treename/packages/B.sub1/meta/package.xml
\section1 Specifying Tree Name to Sub Node
We define a tree name \e{A.subC} for component \e C and set the \c moveChildren attribute
to \c true. Thus, this originally root component is moved as a child component of \e A.
The child components \e {C subcomponent 1} and \e {C subcomponent 2} move
to the new location with the parent.
\quotefile treename/packages/C/meta/package.xml
\section1 Specifying Tree Name to Existing Node
We define a tree name \e D for component \e E. Node \e D is already a part of an existing
component identifier for \e {D subcomponent 1} (\e{D.sub1}), but the packages
directory does not contain a component for the identifier, so it is possible to declare a
tree name \e D. The component \e E becomes a new root component and parent of
\e {D subcomponent 1}. As the \c moveChildren attribute is set to \c true, the
child component \e {E subcomponent 2} is moved with the parent.
\quotefile treename/packages/E/meta/package.xml
\section1 Other Considerations
\section2 Multiple Tree Names in One Component Branch
Components in a single branch (\e A, \e{A.sub1}, \e{A.sub1.sub1}, \e{A.sub1.sub1.sub2} and so
on) may each declare a separate tree name. The installer or maintenance tool calculates the
new locations for components in an ascending order from leaf components to root components, so that
\e{A.sub1.sub1.sub2} is moved first and \e A last.
\section2 Tree Names of Installed and Remote Components
For online installers, the repositories may declare updated tree names for components,
so the following rules apply:
\list
\li The tree names for components become static after being installed. Therefore, if the user
of the installer has installed component \e A with tree name \e ANewName1, and the
repository is updated with a new version of component \e A that declares tree name
\e ANewName2, the new location is only applied when the user updates the component
locally with the maintenance tool.
\li The automatic tree names of children of components with tree name and \c moveChildren
set to \c true are moved with the parent regardless if installed or not. Therefore, if
the user has installed component \e{A.sub1} but not component \e A, and \e A is updated
in the repository with a new tree name, the \e{A.sub1} uses also the new tree name in
maintenance tool's component tree.
\endlist
\section2 Tree Name and Name Conflicts
The tree names may conflict with existing component names or other tree names. Depending on whether
the installer or maintenance tool is configured to allow unstable components with
\c <AllowUnstableComponents> configuration file element, the offending components are either
registered as unstable components with their original name or not registered at all.
\note Components from remote repositories can never override already installed
components in the tree view. If a conflicting remote component cannot be registered with
the original name either in case a local component has reserved it with a tree name, the
component is not registered.
\include installerfw-examples-generating.qdocinc
*/
|
