The metadata a control module embeds with Q_PLUGIN_METADATA: More...
#include <PhosphorControl/ModuleMetadata.h>
Public Member Functions | |
| const ModulePageMetadata * | page (const QString &id) const |
The page with local id id, or nullptr. | |
| const ModuleExtensionMetadata * | extension (const QString &id) const |
The extension with local id id, or nullptr. | |
| int | slotVersion (const QString &pageId, const QString &slot) const |
The version slot slot of the local page pageId offers, or 0 when the page has no such slot. | |
Static Public Member Functions | |
| static ModuleMetadata | parse (const QJsonObject &json, const QLocale &locale, QStringList *errors, QStringList *warnings=nullptr) |
Parse json for locale. | |
Public Attributes | |
| QString | id |
| int | apiVersion = 0 |
| QString | name |
| QString | description |
| QString | icon |
| QString | category |
| The category the module's node goes under when it is not nested under parent: when it names none, when that module is not available, or when nesting under it would close a cycle. | |
| QString | parent |
| Another module's id to nest this module's node under, or empty. | |
| int | order = 0 |
| QStringList | keywords |
| QString | translationDomain |
| Read and kept for the module's own use. | |
| QList< ModuleCategoryMetadata > | categories |
| QList< ModulePageMetadata > | pages |
| Pre-order: each page is followed by its local descendants, and siblings keep their declaration order, which is the order the sidebar shows them in. | |
| QList< ModuleExtensionPointMetadata > | extensionPoints |
| QList< ModuleExtensionMetadata > | extensions |
| QList< ModuleSearchEntryMetadata > | search |
| bool | searchProviders = false |
The metadata a control module embeds with Q_PLUGIN_METADATA:
{
"Id": "plasmazones", "ApiVersion": 1,
"Name": "KWin and Plasma", "Name[de]": "KWin und Plasma",
"Description": "...", "Icon": "org.phosphor_works.PlasmaZones",
"Category": "window-management", "Parent": "placement", "Order": 20,
"Keywords": ["kwin"], "TranslationDomain": "control-module-plasmazones",
"Categories": [{"Id": "...", "Name": "...", "Icon": "...", "Order": 0}],
"Pages": [{"Id": "effect", "Name": "KWin Effect", "Icon": "...",
"Parent": "", "Category": "", "Keywords": ["blur"],
"Visibility": "AdvancedOnly", "DividerAfter": false,
"Counterpart": "", "Anchors": ["blur"]}],
"ExtensionPoints": [{"Page": "effect", "Id": "outline", "Version": 1}],
"Extensions": [{"Id": "snap-assist", "Target": "placement:snapping/behavior",
"Slot": "after:drag-modifier", "TargetVersion": 1,
"Name": "KWin snap assist", "Keywords": ["assist"], "Order": 10}],
"Search": [{"Page": "effect", "Anchor": "blur", "Kind": "Setting", "Title": "Blur",
"Keywords": ["frost"], "AdvancedOnly": false}],
"SearchProviders": false
}
The localizable keys may carry [<locale>] variants (Name[de], Name[pt_BR]): Name, Description and Keywords on the module, Name on a category, Name and Keywords on a page and on an extension, and Title and Keywords on a search entry. A locale is written with '_', never '-': Name[pt-BR] is never picked, and parse() warns about it. phosphor_add_control_module_metadata() writes the variants into the module's metadata from its translations when it is built, keyed by the language and its script (Name[de_Latn], Name[zh_Hant]) where only one catalog claims them, so every locale of that language and script finds it, and by the catalog's own language otherwise, in Qt's code for it (nb, never no, and zh_TW for zho_TW). The bare code of a language Qt has locales for in more than one script (zh, sr, uz) is never a key, since every locale of the language lists it whatever its script: a catalog for it is keyed by the script Qt reads it in (Name[zh_Hans], Name[sr_Cyrl]) even beside a regional catalog, which keeps its own key (Name[zh_CN]), and the build fails when another catalog claims that key too (zh_Hans beside zh). A language of one script keeps its bare key (Name[de] beside Name[de_AT]). An old code for a language written in more than one script that names no script is kept under its own key, which no locale picks: the build warns about sh and asks for the script (sr_Latn). The build keeps a usable variant written by hand, which wins over the catalog's at the catalog's key, at the language and script when the catalog keeps its own longer key, and at the bare language when the catalog's script is the language's usual one, so a hand-written Name[zh] counts as Simplified Chinese and holds off a zh_CN catalog but not a zh_TW one. A variant written by hand uses Qt's code for the language too, since Name[no] is never picked. parse() picks the best variant for the locale, following the locale's UI languages from the most specific form to the bare language (de_Latn_AT, de_AT, de_Latn, de), and skips one that is empty or not of the key's type. Whether a required key (Name, a search entry's Title) is there is decided on its base value alone, so metadata valid in one locale is valid in all of them. The base values are what lupdate extracts: a string must hold no control character other than tab and newline, no U+FFFE or U+FFFF and no half of a surrogate pair, and every Keywords entry must be a non-empty string.
Visibility is Always (the default), AdvancedOnly or SimpleOnly. A module must declare at least one page, even one that only adds sections to other modules' pages: its own page is where the host says why it did not load and offers to load it again. Keys parse() does not know are reported as warnings, not errors, so metadata written for a newer PhosphorControl still loads.
Anchors match [A-Za-z0-9][A-Za-z0-9._-]*, and a search entry's anchor must be one its page lists. SearchProviders says the module registers dynamic search providers, so the host loads it the first time the user searches.
|
nodiscard |
The extension with local id id, or nullptr.
|
nodiscard |
The page with local id id, or nullptr.
|
static |
Parse json for locale.
Every problem is appended to errors, and the metadata is usable only when none was added. What leaves it usable is appended to warnings when it is given: an unknown key or a search entry of an unknown Kind, either of which a newer PhosphorControl may know, and a [<locale>] variant whose locale is malformed (Name[pt-BR], Name[]), which no locale ever picks. A well-formed variant no locale lists, such as Name[no], is not reported.
|
nodiscard |
The version slot slot of the local page pageId offers, or 0 when the page has no such slot.
top and bottom always exist, before:<a> and after:<a> exist for each of the page's anchors, and all of them carry the version of the page's anchors extension point (1 when it declares none). A named slot carries its own version. PageHost places top and bottom around every page. The page's own QML places the anchor and named slots, each with a ExtensionSlot.
| int PhosphorControl::ModuleMetadata::apiVersion = 0 |
| QList<ModuleCategoryMetadata> PhosphorControl::ModuleMetadata::categories |
| QString PhosphorControl::ModuleMetadata::category |
The category the module's node goes under when it is not nested under parent: when it names none, when that module is not available, or when nesting under it would close a cycle.
Empty, or a category no module and not the host defines, means apps.
| QString PhosphorControl::ModuleMetadata::description |
| QList<ModuleExtensionPointMetadata> PhosphorControl::ModuleMetadata::extensionPoints |
| QList<ModuleExtensionMetadata> PhosphorControl::ModuleMetadata::extensions |
| QString PhosphorControl::ModuleMetadata::icon |
| QString PhosphorControl::ModuleMetadata::id |
| QStringList PhosphorControl::ModuleMetadata::keywords |
| QString PhosphorControl::ModuleMetadata::name |
| int PhosphorControl::ModuleMetadata::order = 0 |
| QList<ModulePageMetadata> PhosphorControl::ModuleMetadata::pages |
Pre-order: each page is followed by its local descendants, and siblings keep their declaration order, which is the order the sidebar shows them in.
| QString PhosphorControl::ModuleMetadata::parent |
Another module's id to nest this module's node under, or empty.
When that module is not available the node goes under category instead.
| QList<ModuleSearchEntryMetadata> PhosphorControl::ModuleMetadata::search |
| bool PhosphorControl::ModuleMetadata::searchProviders = false |
| QString PhosphorControl::ModuleMetadata::translationDomain |
Read and kept for the module's own use.
the host does not load a catalog by it: the metadata's strings come translated from the module's TS_FILES (phosphor_add_control_module_metadata()), and the module installs a translator for its QML itself.