FlightGear next
Addon.hxx
Go to the documentation of this file.
1// -*- coding: utf-8 -*-
2//
3// Addon.hxx --- FlightGear class holding add-on metadata
4// Copyright (C) 2017, 2018 Florent Rougon
5//
6// This program is free software; you can redistribute it and/or modify
7// it under the terms of the GNU General Public License as published by
8// the Free Software Foundation; either version 2 of the License, or
9// (at your option) any later version.
10//
11// This program is distributed in the hope that it will be useful,
12// but WITHOUT ANY WARRANTY; without even the implied warranty of
13// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14// GNU General Public License for more details.
15//
16// You should have received a copy of the GNU General Public License along
17// with this program; if not, write to the Free Software Foundation, Inc.,
18// 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
19
20#ifndef FG_ADDON_HXX
21#define FG_ADDON_HXX
22
23#include <map>
24#include <ostream>
25#include <string>
26#include <vector>
27
28#include <simgear/misc/sg_path.hxx>
29#include <simgear/nasal/cppbind/NasalHash.hxx>
30#include <simgear/nasal/naref.h>
31#include <simgear/props/props.hxx>
32#include <simgear/structure/SGReferenced.hxx>
33
34#include "addon_fwd.hxx"
35#include "contacts.hxx"
36#include "AddonVersion.hxx"
37#include "pointer_traits.hxx"
38
39namespace flightgear
40{
41
42namespace addons
43{
44
54
56{
57public:
58 QualifiedUrl(UrlType type, std::string url, std::string detail = "");
59
60 UrlType getType() const;
61 void setType(UrlType type);
62
63 std::string getUrl() const;
64 void setUrl(const std::string& url);
65
66 std::string getDetail() const;
67 void setDetail(const std::string& detail);
68
69private:
70 UrlType _type;
71 std::string _url;
72 // Used to store the author or maintainer name when _type is UrlType::author
73 // or UrlType::maintainer. Could be used to record details about a website
74 // too (e.g., for a UrlType::support, something like “official forum”).
75 std::string _detail;
76};
77
78class Addon : public SGReferenced
79{
80public:
81 // An empty value for 'minFGVersionRequired' is translated into "2017.4.0".
82 // An empty value for 'maxFGVersionRequired' is translated into "none".
83 Addon(std::string id, AddonVersion version = AddonVersion(),
84 SGPath basePath = SGPath(), std::string minFGVersionRequired = "",
85 std::string maxFGVersionRequired = "",
86 SGPropertyNode* addonNode = nullptr);
87
88 // Parse the add-on metadata file inside 'addonPath' (as defined by
89 // getMetadataFile()) and return the corresponding Addon instance.
90 static Addon fromAddonDir(const SGPath& addonPath);
91
92 template<class T>
93 static T fromAddonDir(const SGPath& addonPath)
94 {
95 using ptr_traits = shared_ptr_traits<T>;
96 return ptr_traits::makeStrongRef(fromAddonDir(addonPath));
97 }
98
99 std::string getId() const;
100
101 std::string getName() const;
102 void setName(const std::string& addonName);
103
105 void setVersion(const AddonVersion& addonVersion);
106
107 std::vector<AuthorRef> getAuthors() const;
108 void setAuthors(const std::vector<AuthorRef>& addonAuthors);
109
110 std::vector<MaintainerRef> getMaintainers() const;
111 void setMaintainers(const std::vector<MaintainerRef>& addonMaintainers);
112
113 std::string getShortDescription() const;
114 void setShortDescription(const std::string& addonShortDescription);
115
116 std::string getLongDescription() const;
117 void setLongDescription(const std::string& addonLongDescription);
118
119 std::string getLicenseDesignation() const;
120 void setLicenseDesignation(const std::string& addonLicenseDesignation);
121
122 SGPath getLicenseFile() const;
123 void setLicenseFile(const SGPath& addonLicenseFile);
124
125 std::string getLicenseUrl() const;
126 void setLicenseUrl(const std::string& addonLicenseUrl);
127
128 std::vector<std::string> getTags() const;
129 void setTags(const std::vector<std::string>& addonTags);
130
131 SGPath getBasePath() const;
132 void setBasePath(const SGPath& addonBasePath);
133
134 // Return $FG_HOME/Export/Addons/ADDON_ID as an SGPath instance.
135 SGPath getStoragePath() const;
136 // Create directory $FG_HOME/Export/Addons/ADDON_ID, including any parent,
137 // if it doesn't already exist. Throw an exception in case of problems.
138 // Return an SGPath instance for the directory (same as getStoragePath()).
139 SGPath createStorageDir() const;
140
141 // Return a resource path suitable for use with the simgear::ResourceManager.
142 // 'relativePath' is relative to the add-on base path, and should not start
143 // with a '/'.
144 std::string resourcePath(const std::string& relativePath) const;
145
146 // Should be valid for use with simgear::strutils::compare_versions()
147 std::string getMinFGVersionRequired() const;
148 void setMinFGVersionRequired(const std::string& minFGVersionRequired);
149
150 // Should be valid for use with simgear::strutils::compare_versions(),
151 // except for the special value "none".
152 std::string getMaxFGVersionRequired() const;
153 void setMaxFGVersionRequired(const std::string& maxFGVersionRequired);
154
155 std::string getHomePage() const;
156 void setHomePage(const std::string& addonHomePage);
157
158 std::string getDownloadUrl() const;
159 void setDownloadUrl(const std::string& addonDownloadUrl);
160
161 std::string getSupportUrl() const;
162 void setSupportUrl(const std::string& addonSupportUrl);
163
164 std::string getCodeRepositoryUrl() const;
165 void setCodeRepositoryUrl(const std::string& addonCodeRepositoryUrl);
166
167 std::string getTriggerProperty() const;
168 void setTriggerProperty(const std::string& addonTriggerProperty);
169
170 // Node pertaining to the add-on in the Global Property Tree
171 SGPropertyNode_ptr getAddonNode() const;
172 void setAddonNode(SGPropertyNode* addonNode);
173 // For Nasal: result as a props.Node object
174 naRef getAddonPropsNode() const;
175
176 // Property node indicating whether the add-on is fully loaded
177 SGPropertyNode_ptr getLoadedFlagNode() const;
178
179 // 0 for the first loaded add-on, 1 for the second, etc.
180 // -1 means “not set” (as done by the default constructor)
181 int getLoadSequenceNumber() const;
182 void setLoadSequenceNumber(int num);
183
184 // Get all non-empty URLs pertaining to this add-on
185 std::multimap<UrlType, QualifiedUrl> getUrls() const;
186
187 // Getter and setter for the menu bar item nodes of the add-on
188 std::vector<SGPropertyNode_ptr> getMenubarNodes() const;
189 void setMenubarNodes(const std::vector<SGPropertyNode_ptr>& menubarNodes);
190 // Add the menus defined in addon-menubar-items.xml to /sim/menubar/default
191 void addToFGMenubar() const;
192
193 // Simple string representation
194 std::string str() const;
195
196 static void setupGhost(nasal::Hash& addonsModule);
197
201 void retranslate();
202
203 private:
204 class Metadata;
205 class MetadataParser;
206
207 // “Compute” a path to the metadata file from the add-on base path
208 static SGPath getMetadataFile(const SGPath& addonPath);
209 SGPath getMetadataFile() const;
210
211 // Read all menus from addon-menubar-items.xml (under the add-on base path)
212 static std::vector<SGPropertyNode_ptr>
213 readMenubarItems(const SGPath& menuFile);
214
215 // The add-on identifier, in reverse DNS style. The AddonManager refuses to
216 // register two add-ons with the same id in a given FlightGear session.
217 const std::string _id;
218 // Pretty name for the add-on (not constrained to reverse DNS style)
219 std::string _name;
220 // Use a smart pointer to expose the AddonVersion instance to Nasal without
221 // needing to copy the data every time.
222 AddonVersionRef _version;
223
224 std::vector<AuthorRef> _authors;
225 std::vector<MaintainerRef> _maintainers;
226
227 // Strings describing what the add-on does
228 std::string _shortDescription;
229 std::string _longDescription;
230
231 std::string _licenseDesignation;
232 SGPath _licenseFile;
233 std::string _licenseUrl;
234
235 std::vector<std::string> _tags;
236 SGPath _basePath;
237 // $FG_HOME/Export/Addons/ADDON_ID
238 const SGPath _storagePath;
239
240 // To be used with simgear::strutils::compare_versions()
241 std::string _minFGVersionRequired;
242 // Ditto, but there is a special value: "none"
243 std::string _maxFGVersionRequired;
244
245 std::string _homePage;
246 std::string _downloadUrl;
247 std::string _supportUrl;
248 std::string _codeRepositoryUrl;
249
250 // Main node for the add-on in the Property Tree
251 SGPropertyNode_ptr _addonNode;
252 // The add-on will be loaded when the property referenced by
253 // _triggerProperty is written to.
254 std::string _triggerProperty;
255 // Semantics explained above
256 int _loadSequenceNumber = -1;
257
258 std::vector<SGPropertyNode_ptr> _menubarNodes;
259};
260
261std::ostream& operator<<(std::ostream& os, const Addon& addon);
262
263} // of namespace addons
264
265} // of namespace flightgear
266
267#endif // of FG_ADDON_HXX
Addon(std::string id, AddonVersion version=AddonVersion(), SGPath basePath=SGPath(), std::string minFGVersionRequired="", std::string maxFGVersionRequired="", SGPropertyNode *addonNode=nullptr)
Definition Addon.cxx:90
void retranslate()
update string values (description, etc) based on the active locale
Definition Addon.cxx:471
SGPropertyNode_ptr getLoadedFlagNode() const
Definition Addon.cxx:297
void setLicenseFile(const SGPath &addonLicenseFile)
Definition Addon.cxx:163
naRef getAddonPropsNode() const
Definition Addon.cxx:291
void setLongDescription(const std::string &addonLongDescription)
Definition Addon.cxx:151
void setSupportUrl(const std::string &addonSupportUrl)
Definition Addon.cxx:270
void setCodeRepositoryUrl(const std::string &addonCodeRepositoryUrl)
Definition Addon.cxx:276
void setBasePath(const SGPath &addonBasePath)
Definition Addon.cxx:181
void setLicenseUrl(const std::string &addonLicenseUrl)
Definition Addon.cxx:169
Addon(std::string id, AddonVersion version=AddonVersion(), SGPath basePath=SGPath(), std::string minFGVersionRequired="", std::string maxFGVersionRequired="", SGPropertyNode *addonNode=nullptr)
Definition Addon.cxx:90
std::string str() const
Definition Addon.cxx:351
std::string getMaxFGVersionRequired() const
Definition Addon.cxx:243
void setLoadSequenceNumber(int num)
Definition Addon.cxx:305
void setMaintainers(const std::vector< MaintainerRef > &addonMaintainers)
Definition Addon.cxx:139
std::string getSupportUrl() const
Definition Addon.cxx:267
std::string getShortDescription() const
Definition Addon.cxx:142
std::string getMinFGVersionRequired() const
Definition Addon.cxx:237
void setMinFGVersionRequired(const std::string &minFGVersionRequired)
Definition Addon.cxx:240
void setAddonNode(SGPropertyNode *addonNode)
Definition Addon.cxx:288
void setTriggerProperty(const std::string &addonTriggerProperty)
Definition Addon.cxx:282
int getLoadSequenceNumber() const
Definition Addon.cxx:302
void setName(const std::string &addonName)
Definition Addon.cxx:118
SGPath getStoragePath() const
Definition Addon.cxx:184
void setMaxFGVersionRequired(const std::string &maxFGVersionRequired)
Definition Addon.cxx:246
static T fromAddonDir(const SGPath &addonPath)
Definition Addon.hxx:93
SGPath getBasePath() const
Definition Addon.cxx:178
std::multimap< UrlType, QualifiedUrl > getUrls() const
Definition Addon.cxx:308
void setDownloadUrl(const std::string &addonDownloadUrl)
Definition Addon.cxx:264
static Addon fromAddonDir(const SGPath &addonPath)
Definition Addon.cxx:374
std::string getTriggerProperty() const
Definition Addon.cxx:279
std::string getHomePage() const
Definition Addon.cxx:255
SGPath getLicenseFile() const
Definition Addon.cxx:160
void setVersion(const AddonVersion &addonVersion)
Definition Addon.cxx:124
void addToFGMenubar() const
Definition Addon.cxx:341
std::string getDownloadUrl() const
Definition Addon.cxx:261
AddonVersionRef getVersion() const
Definition Addon.cxx:121
std::vector< AuthorRef > getAuthors() const
Definition Addon.cxx:130
std::vector< MaintainerRef > getMaintainers() const
Definition Addon.cxx:136
std::vector< SGPropertyNode_ptr > getMenubarNodes() const
Definition Addon.cxx:335
std::string getName() const
Definition Addon.cxx:115
std::string getLicenseUrl() const
Definition Addon.cxx:166
std::string getId() const
Definition Addon.cxx:112
std::string getLongDescription() const
Definition Addon.cxx:148
void setAuthors(const std::vector< AuthorRef > &addonAuthors)
Definition Addon.cxx:133
SGPropertyNode_ptr getAddonNode() const
Definition Addon.cxx:285
static void setupGhost(nasal::Hash &addonsModule)
Definition Addon.cxx:480
std::string resourcePath(const std::string &relativePath) const
Definition Addon.cxx:226
void setHomePage(const std::string &addonHomePage)
Definition Addon.cxx:258
void setTags(const std::vector< std::string > &addonTags)
Definition Addon.cxx:175
void setLicenseDesignation(const std::string &addonLicenseDesignation)
Definition Addon.cxx:157
SGPath createStorageDir() const
Definition Addon.cxx:187
std::string getLicenseDesignation() const
Definition Addon.cxx:154
std::string getCodeRepositoryUrl() const
Definition Addon.cxx:273
std::vector< std::string > getTags() const
Definition Addon.cxx:172
void setShortDescription(const std::string &addonShortDescription)
Definition Addon.cxx:145
void setMenubarNodes(const std::vector< SGPropertyNode_ptr > &menubarNodes)
Definition Addon.cxx:338
std::string getUrl() const
Definition Addon.cxx:74
QualifiedUrl(UrlType type, std::string url, std::string detail="")
Definition Addon.cxx:62
void setUrl(const std::string &url)
Definition Addon.cxx:77
void setDetail(const std::string &detail)
Definition Addon.cxx:83
void setType(UrlType type)
Definition Addon.cxx:71
std::string getDetail() const
Definition Addon.cxx:80
std::ostream & operator<<(std::ostream &os, const Addon &addon)
Definition Addon.cxx:509
SGSharedPtr< AddonVersion > AddonVersionRef
Definition addon_fwd.hxx:47
FlightPlan.hxx - defines a full flight-plan object, including departure, cruise, arrival information ...
Definition Addon.cxx:53