Meta podaci dodatka

Datoteka s metapodacima dodatka je JSON datoteka koja sadrži sve informacije potrebne za učitavanje biblioteke dodatka, određivanje hoće li se dodaci učitavati i kojim redoslijedom (ovisno o, npr., ovisnostima). Osim toga, sadrži tekstualne opise tko je stvorio dodatak, čemu služi i gdje pronaći više informacija o njemu. Datoteka mora biti smještena na jednoj od uključnih putova pretraživanja prilikom kompajliranja dodatka i mora imati ekstenziju .json. JSON datoteka se kompajlira u dodatak kao metapodaci, koje zatim Qt Creator čita prilikom učitavanja dodataka.

Glavni ključevi

Glavni ključevi koji se koriste za identifikaciju vašeg dodatka i definiranje zadanog ponašanja pri učitavanju sastoje se od obaveznih ključeva Id i Version te neobaveznih ključeva CompatVersion, Experimental, DisabledByDefault, Required i Platform.

Ključevi koji opisuju dodatak

Ovi se koriste isključivo za detaljniji (korisnički usmjeren) opis dodatka. Svi su opcionalni.

Ovisnosti

Dodatak može imati ovisnosti o drugim dodacima. One se navode u metapodacima dodatka kako bi se osiguralo da se ti drugi dodaci učita prije ovog dodatka.

Ovisnosti se deklariraju ključem Dependency, koji sadrži niz JSON objekata sa obaveznim ključevima Id i Version te opcionalnim ključem Type.

Sljedeće formule ilustriraju kako se podudara informacija o ovisnosti. U formulama je Id potrebnog dodatka (kako je definirano u Id objektu ovisnosti) označen kao DependencyId, a potrebna verzija dodatka označena je kao DependencyVersion. Dodatak s danim Id, Version i CompatVersion kako je definirano u metapodacima dodatka podudara se s ovisnošću ako

• njegov Id odgovara DependencyId, i
• CompatVersion <= DependencyVersion <= Version. Na primjer, ovisnost

Na primjer, ovisnost

{
    "Id" : "someotherplugin",
    "Version" : "2.3.0_2"
}

bi odgovarala dodatku s

{
    "Id" : "someotherplugin",
    "Name" : "SomeOtherPlugin",
    "Version" : "3.1.0",
    "CompatVersion" : "2.2.0",
    ...
}

budući da ID odgovara, a verzija 2.3.0_2 navedena u tagu ovisnosti nalazi se u rasponu od 2.2.0 do 3.1.0.

Objekt ovisnosti je JSON objekt sa sljedećim ključevima:

Izborne ovisnosti

Plugin može navesti da je ovisnost o drugom pluginu neobavezna dodavanjem "Type" : "optional" u objekt ovisnosti:

• Ako se ovisnost može riješiti, dodatak i njegova ovisnost se učitavaju i inicijaliziraju kao kod ovisnosti required.
• Ako se ovisnost ne može riješiti, dodatak se učitava i inicijalizira kao da ovisnost uopće nije bila deklarirana.

Dodatak se ni na koji način ne obavještava o postojanju neobaveznih ovisnosti. Budući da ovisnost može biti učitana ili ne, dodatak se također možda neće povezati s ovisnošću. Uobičajen način za pristup objektima iz neobaveznih ovisnosti jest dobivanje objekta iz globalnog fonda objekata putem ExtensionSystem::PluginManager::getObjectByName() i korištenje funkcija QMetaObject za pozivanje funkcija na njemu.

Testne ovisnosti

Kada korisnik pokrene aplikaciju s argumentom naredbenog retka -test, učitavaju se samo navedeni dodaci i njihove ovisnosti. To se radi kako bi se ubrzalo izvršavanje testova izbjegavanjem učitavanja nepotrebnih dodataka.

Plugin može navesti dodatne ovisnosti koje su potrebne za pokretanje njegovih testova, ali ne i za njegovo normalno izvršavanje, deklariranjem ovisnosti pomoću "Type" : "test". Testne ovisnosti se obavezno učitavaju i ne utječu na redoslijed učitavanja.

Ova vrsta ovisnosti nije tranzitivna.

Argumenti naredbenog retka

Dodaci mogu registrirati argumente naredbenog retka koje korisnik može unijeti pri pokretanju aplikacije. Ti se argumenti naredbenog retka prikazuju s jednolinijskim opisom kada korisnik pokrene aplikaciju s argumentom naredbenog retka -help, a upravitelj dodataka vrši analizu naredbenog retka i provjere ispravnosti na temelju tih informacija. Ako upravitelj dodataka pronađe odgovarajuće argumente naredbenog retka za dodatak, prosljeđuje ih funkciji initialize() dodatka.

Argumenti naredbenog retka definiraju se putem ključa Arguments, koji sadrži niz objekata argumenata. Svaki pojedinačni objekt argumenta ima obavezni ključ Name i opcionalne ključeve Parameter i Description.

Objekt argumenta je JSON objekt sa sljedećim ključevima:

Primjer Test.json

{
    "Id" : "test",
    "Name" : "Test",
    "Version" : "1.0.1",
    "CompatVersion" : "1.0.0",
    "VendorId" : "mycompany",
    "Vendor" : "My Company",
    "Copyright" : "(C) 2016 MyCompany",
    "License" : [
        "This is a default license bla",
        "blubbblubb",
        "end of terms"
    ],
    "Category" : "My Company Additions",
    "Description" : [
        "This plugin is just a test.",
        "It demonstrates the great use of the plugin meta data."
    ],
    "Url" : "https://www.mycompany-online.com/products/greatplugin",
    "DocumentationUrl" : "https://www.mycompany-online.com/docs/greatplugin/manual.html",
    "Arguments" : [
        {
            "Name" : "-variant",
            "Parameter" : "fancy|boring",
            "Description" : "Brings up the fancy or boring user interface"
        }
    ],
    "Dependencies" : [
        { "Id" : "someotherplugin", "Version" : "2.3.0_2" },
        { "Id" : "evenother", "Version" : "1.0.0" }
    ]
}

Ostali metapodaci

key u obliku FirstKey > SecondKey znači da je vrijednost za FirstKey JSON objekt koji uključuje SecondKey.

Napomena o verzijama dodataka

Verzije dodataka su u obliku x.y.z_n, gdje su x, y, z i n ne-negativni cjelobrojni brojevi. Ne morate navesti verziju u ovom punom obliku – svaki izostavljeni dio implicitno će se postaviti na nulu. Dakle, 2.10_2 jednako je 2.10.0_2, a 1 isto je kao 1.0.0_0.