Izrada dodataka temeljenih na C++-u

Ova tema opisuje kako stvoriti dodatak za Qt Creator temeljen na C++-u i steći prvi dojam o njegovom sadržaju i strukturi.

Kreiranje projekta C++ dodatka

Qt Creator dolazi s čarobnjakom za C++ dodatke za Qt Creator, koji za vas stvara minimalni pokretni dodatak. Toplo vam preporučujemo da za razvoj i testiranje dodatka koristite dva različita primjerka Qt Creator. U suprotnom će se vaš dodatak također učitati u vaše razvojno okruženje, što ga može učiniti nestabilnim dok je vaš dodatak još uvijek nestabilan. Možete jednostavno napraviti kopiju svoje Qt Creator izgradnje i koristiti jednu za stvarni razvoj, a drugu za testiranje dodatka.

Morate se pobrinuti da za izradu dodatka koristite istu verziju Qt Creator za koju želite razvijati. Zbog pravila o binarnoj i izvornoj kompatibilnosti sustava Qt Creator, čarobnjak za dodatke Qt Creator stvara dodatak koji se možda može kompajlirati i pokrenuti samo s istom verzijom Qt Creator s kojom je stvoren.

1. Odaberite File > New Project > Library > Qt Creator C++ Plugin > Choose.

   

   Otvorit će se dijalog Introduction and Project Location.

   

2. Dajte svom projektu naziv i navedite putanju u kojoj će projekt biti stvoren. Stvarni naziv dodatka može se razlikovati od naziva projekta. Taj ćete naziv odabrati kasnije u čarobnjaku.
3. Nastavite na dijalog Plugin Information.

   

4. U polje Plugin name upišite Example. Naziv dodatka služi kao njegov identifikator, a također je i osnova za nazive datoteka i klasa u kodu.
5. Vrijednosti sljedećih polja uglavnom su informativne i prikazuju se u detaljnom prikazu u pregledu dodataka Qt Creator a (Help > About Plugins, ili Qt CreatorAbout Plugins na macOS-u).
   • Vendor name je kratko jednoriječno ime tvrtke ili organizacije koja je izradila dodatak. Također se koristi za naziv putanje na koju će se dodatak raspakirati.
   • Copyright je kratki tekst autorskih prava na jednoj liniji.
   • License je tekst licence.
   • Description je kratak opis onoga što dodatak radi.
   • URL je web-stranica na kojoj korisnik može pronaći više informacija o dodatku i/ili organizaciji koja ga pruža.
6. Postavite Qt Creator build polje na direktorij za izgradnju instance Qt Creator -a koju želite koristiti za testiranje svog dodatka. Ako to ne učinite ispravno, dobit ćete pogreške pri kompilaciji vašeg dodatka, a vaš dodatak se možda uopće neće pojaviti u Qt Creator.
7. Nastavite na dijalog Translation File.

   

8. Odaberite jezik na koji želite lokalizirati svoj dodatak. Time se postavlja podrška za prijevod za odabrani jezik.
9. Kit Selection Nastavite na dijalog za izradu i pokretanje projekta.

   

10. Odaberite komplet za izradu i pokretanje vašeg projekta. Za dodatak za Qt Creator, to mora biti komplet s tipom uređaja Desktop i verzijom Qt-a koja je kompatibilna s verzijom Qt-a s kojom je vaš Qt Creator izgrađen (u najboljem slučaju potpuno ista izrada). Ako koristite nekompatibilnu verziju Qt-a za izradu dodatka, dobit ćete pogreške dok Qt Creator pokušava učitati vaš dodatak.
11. Nastavite na dijalog za Project Management.

    

12. Pregledajte datoteke koje će biti stvorene, odaberite sustav za kontrolu verzija koji bi Qt Creator trebao koristiti za vaš projekt (uvijek dobra ideja!) i završite čarobnjak.

Izrada i pokretanje dodatka

Ako ste u čarobnjaku za projekt unijeli ispravnu putanju do izgradnje Qt Creator, vaš bi se dodatak trebao bez problema izgraditi kada pritisnete gumb za izgradnju. Prije pokretanja projekta odaberite Build & Run > Run kako biste specificirali postavke pokretanja:

Odaberite putanju do izvršne datoteke Qt Creator izgradnje koju ste naveli u Qt Creator build polju u čarobnjaku za projekt i postavite vrijednost polja Command line arguments na -pluginpath %{buildDir}.

Kada odaberete OK, pokrenut će se Qt Creator i možete provjeriti je li vaš dodatak uspješno učitano traženjem stavke izbornika Tools > Example i traženjem dodatka u dijalogu Help > About Plugins.

Struktura datoteka

Čarobnjak za dodatke stvara skup osnovnih datoteka koje dodatak treba ili bi ih trebao imati. Neke od njih detaljnije ćemo pogledati u sljedećim odjeljcima, a ovdje je kratak pregled:

CMake projekt

Datoteka CMake projektnog projekta CMakeLists.txt definira kako bi vaš dodatak trebao biti kompajliran. Dodaci za Qt Creator moraju imati specifičnu konfiguraciju, osim što CMakeu govore koje datoteke treba kompajlirati (ili obraditi pomoću moc ili uic). Pogledajmo detaljno što je čarobnjak za projekt generirao za vas.

# Remove when sharing with others.
list(APPEND CMAKE_PREFIX_PATH "/Users/example/qt-creator/build")

Poziv list(APPEND ...) -u nalaže CMakeu da u svoj put za pretraživanje ovisnosti uključi put do izgradnje Qt Creator -a koji ste naveli u čarobnjaku. Budući da to sadrži apsolutnu putanju na vašoj lokalnoj računali, trebali biste ukloniti ovaj redak kada projekt dijelite s drugima.

Bez ove linije morate izričito dodati putanju do Qt Creator builda u CMAKE_PREFIX_PATH prilikom konfiguriranja vašeg plugina pomoću CMakea.

project(Example)

set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTORCC ON)
set(CMAKE_AUTOUIC ON)
set(CMAKE_CXX_STANDARD 17)

Ovaj odjeljak obavlja neke standardne pripreme za Qt/CMake projekte. Osim postavljanja naziva projekta i C++ standarda koji se koristi, on omogućuje automatsko otkrivanje datoteka koje treba pokrenuti kroz moc, rcc ili uic.

find_package(QtCreator COMPONENTS Core REQUIRED)
find_package(QT NAMES Qt6 Qt5 COMPONENTS Widgets REQUIRED)
set(QtX Qt${QT_VERSION_MAJOR})

Ovaj odjeljak CMakeu nalaže da pronađe Qt Creator i Qt. Ako vaš dodatak zahtijeva dodatne Qt module, morate ih dodati u odgovarajući poziv find_package u ovom odjeljku.

Da bi pronašao Qt Creator i Qt, putanje do instalacija Qt Creator i Qt moraju biti prisutne u CMAKE_PREFIX_PATH kada konfigurirate svoj dodatak pomoću CMakea.

add_qtc_plugin(Example
  PLUGIN_DEPENDS
    QtCreator::Core
  DEPENDS
    ${QtX}::Widgets
    QtCreator::ExtensionSystem
    QtCreator::Utils
  SOURCES
    .github/workflows/build_cmake.yml
    .github/workflows/README.md
    README.md
    example.cpp
    example.h
    example_global.h
    exampleconstants.h
    examplefunctions.h
)

Poziv add_qtc_plugin stvara cilj za vaš dodatak s navedenim imenom.

U pododjeljku PLUGIN_DEPENDS morate navesti Qt Creator -plugine na koje vaš plugin ovisi. Valjane vrijednosti su naziv plugina s prefiksom QtCreator::.

U pododjeljku DEPENDS morate navesti biblioteke na koje vaš dodatak ovisi. Koristite naziv Qt modula s prefiksom $\{QtX\}:: za povezivanje s dodatnim Qt modulima. Za povezivanje s dodatnim bibliotekama Qt Creator, prednazovite njihov naziv s QtCreator::. U ovom pododjeljku također navodite ostale biblioteke na koje vaš dodatak ovisi.

U pododjeljku SOURCES navodite sve datoteke koje pripadaju vašem projektu dodatka. CMake ih automatski razvrstava na izvorne datoteke i zaglavlja. Druge datoteke u ovom odjeljku CMake ignorira, ali se, primjerice, prikazuju u stablu projekta u IDE-ovima poput Qt Creator radi lakšeg pristupa.

Predložak metapodataka dodatka

Datoteka .json je JSON datoteka koja sadrži informacije potrebne upravitelju dodataka da pronađe vaš dodatak i riješi njegove ovisnosti prije stvarnog učitavanja bibliotečke datoteke vašeg dodatka. Ovdje ćemo je samo ukratko pogledati. Za više informacija pogledajte Meta-podaci dodatka.

Čarobnjak zapravo ne stvara .json datoteku izravno, već .json.in datoteku. qmake to koristi za generiranje stvarne .json meta podatkovne datoteke dodatka, zamjenjujući varijable poput QTCREATOR_VERSION njihovim stvarnim vrijednostima. Stoga morate pobjeći sve nazadne kose crte i navodnike u .json.in datoteci (tj. morate napisati \ da biste dobili nazadnu kosu crtu i \" da biste dobili navodnik u generiranim JSON meta podacima dodatka).

    "Id" : "example",
    "Name" : "Example",
    "Version" : "0.0.1",
    "CompatVersion" : "0.0.1",

Prvi stavci u metapodacima koje stvara čarobnjak definiraju naziv vašeg dodatka, njegovu verziju i verziju dodatka s kojom je trenutna verzija binarno kompatibilna.

    "VendorId" : "mycompany",
    "Vendor" : "MyCompany",
    "Copyright" : "(C) MyCompany",
    "License" : "Put short license information here",
    "Description" : "Put a short description of your plugin here.",
    "Url" : "https://www.mycompany.com",

Nakon toga pronaći ćete informacije o dodatku koje ste unijeli u čarobnjaku za projekt.

    ${IDE_PLUGIN_DEPENDENCIES}

Varijabla IDE_PLUGIN_DEPENDENCIES automatski se zamjenjuje informacijama o ovisnostima iz PLUGIN_DEPENDS i PLUGIN_RECOMMENDS u pozivu add_qtc_plugin() vašeg dodatka u njegovoj datoteci CMakeLists.txt.

Klasa dodatka

Datoteke example.h i example.cpp definiraju implementaciju vašeg malog plugina. Ovdje ćemo se usredotočiti na neke ključne aspekte i dati upute za detaljnije informacije o pojedinim dijelovima.

Glavna datoteka

Glavna datoteka example.h definira sučelje klase dodatka.

namespace Example {
namespace Internal {

Plugin je definiran u imenskom prostoru Example::Internal, koji je u skladu s pravilima kodiranja za imenske prostore u izvorima Qt Creator.

class ExamplePlugin : public ExtensionSystem::IPlugin
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QtCreatorPlugin" FILE "Example.json")

Svi Qt Creator dodaci moraju nasljeđivati od ExtensionSystem::IPlugin i QObject su. Makro Q_PLUGIN_METADATA potreban je za stvaranje valjanog Qt dodatka. IID naveden u makrou mora biti org.qt-project.Qt.QtCreatorPlugin kako bi se prepoznao kao Qt Creator dodatak, a FILE mora upućivati na datoteku s metapodacima dodatka, kao što je opisano u odjeljku Plugin Meta Data.

    bool initialize(const QStringList &arguments, QString *errorString);
    void extensionsInitialized();
    ShutdownFlag aboutToShutdown();

Osnovna klasa definira osnovne funkcije koje se pozivaju tijekom životnog ciklusa dodatka, a koje su ovdje implementirane za vaš novi dodatak. Te su funkcije i njihove uloge detaljno opisane u poglavlju Životni ciklus dodatka.

private:
    void triggerAction();

Plugin ima dodatni prilagođeni slot koji se koristi za otvaranje dijaloga kada korisnik odabere stavku izbornika koju je ovaj dodatak dodao.

Izvorna datoteka

Izvorna datoteka sadrži stvarnu implementaciju dodatka, koji registrira novi izbornik i stavku izbornika te otvara okvir za poruke kada se ta stavka aktivira.

Sve potrebne zaglavne datoteke iz samog koda dodatka, iz dodatka Core i iz Qt-a uključene su na početku datoteke. Postavljanje izbornika i stavke izbornika vrši se u funkciji initialize dodatka, koja se poziva kao prva nakon konstruktora dodatka. U toj funkciji dodatak može biti siguran da je osnovno postavljanje dodataka na koje ovisi dovršeno, na primjer, da je instanca ActionManager dodatka Core stvorena.

Za više informacija o implementaciji sučelja dodatka pogledajte API dokumentaciju za ExtensionSystem::IPlugin i životni ciklus dodatka.

    auto action = new QAction(tr("Example Action"), this);
    Core::Command *cmd = Core::ActionManager::registerAction(action, Constants::ACTION_ID,
                                                             Core::Context(Core::Constants::C_GLOBAL));
    cmd->setDefaultKeySequence(QKeySequence(tr("Ctrl+Alt+Meta+A")));
    connect(action, &QAction::triggered, this, &ExamplePlugin::triggerAction);

Ovaj dio koda stvara novi QAction, registrira ga kao novu Command u upravitelju radnji i povezuje ga s slotom dodatka. Upravitelj radnji pruža središnje mjesto gdje korisnik može dodijeliti i mijenjati prečace na tipkovnici te upravlja slučajevima kada se, na primjer, stavka izbornika treba usmjeriti na različite dodatke u različitim okolnostima, kao i nekim drugim stvarima.

    Core::ActionContainer *menu = Core::ActionManager::createMenu(Constants::MENU_ID);
    menu->menu()->setTitle(tr("Example"));
    menu->addAction(cmd);
    Core::ActionManager::actionContainer(Core::Constants::M_TOOLS)->addMenu(menu);

Ovdje se stvara novi stavak izbornika, dodaje mu se naredba create i taj se izbornik dodaje u izbornik Tools u izborniku trake.

void ExamplePlugin::triggerAction()
{
    QMessageBox::information(Core::ICore::mainWindow(),
                             tr("Action Triggered"),
                             tr("This is an action from Example."));
}

OK Ovaj dio definira kod koji se poziva kada se stavka izbornika aktivira. Koristi Qt API za otvaranje okvira za poruke koji prikazuje informativni tekst i gumb za izlaz.