# &kde; Frameworks: KDesignerPlugin

`kgendesignerplugin`

1

`kgendesignerplugin`

Програма для створення додатків віджетів для &Qt; Designer.

    kgendesignerplugin ПАРАМЕТРИ файл

## Опис

Нетипові додатки віджетів для &Qt; Designer зазвичай мають стандартну структуру, класи, роботу яких забезпечує додаток, здебільшого надають статичну інформацію, а функція для створення екземпляра класу типово є простим викликом конструктора. За допомогою `kgendesignerplugin` розробники бібліотек, які створюють нові віджети, можуть створити такий додаток з усім стандартним кодом на основі простого файла опису у стилі ini.

`kgendesignerplugin` вибирає загальноприйнятні типові значення для більшості параметрів, отже, зазвичай, потрібні лише мінімальні зміни у налаштуваннях.

## Параметри

`-o `файл``

- Назва створеного програмою файла коду C++. Якщо назву не вказано, дані буде виведено до `stdout`.

`-n `назва додатка``

- Забезпечує сумісність із попередніми версіями. Типове значення для параметра PluginName у файлі вхідних даних.

`-g `група``

- Забезпечує сумісність із попередніми версіями. Типове значення для параметра DefaultGroup у файлі вхідних даних.

`--author`

- Вивести дані щодо авторства програми.

`--license`

- Вивести дані щодо умов ліцензування на програму.

`-h, --help`

- Вивести короткий текст довідки.

`-v , --version`

- Вивести дані щодо версії програми.

## Формат файлів

Файл вхідних даних є файлом налаштувань у стилі ini (якщо бути точнішим, то у форматі, підтримуваному бібліотекою KConfig), який містить опис набору віджетів. У ньому має бути розділ `[Global]`, де наведено загальні відомості щодо додатка, та окремий розділ для кожного з віджетів, які має бути включено до додатка.

У розділі `[Global]` може бути вказано такі записи:

`DefaultGroup`

- Типове значення для запису `Group` у розділах класів (типове значення: "`Custom`", якщо не вказано параметра `-g`).

`Includes`

- Список включень, відокремлених комами (типове значення: порожній). Зауважте, що тут не слід вказувати файли заголовків, які пізніше буде вказано у файлі; це лише спеціальні файли заголовків, які використовуватимуться лише самим додатком, якщо заголовки для класів, які надають можливість попереднього перегляду.

`PluginName`

- Назва основного класу C++ у додатку (типове значення: `WidgetsPlugin`, якщо не вказано параметра `-n`).

У кожного класу має бути власний розділ `[`ClassName`]`, у якому мають бути такі записи:

`CodeTemplate`

- Значення, яке повертає функція `codeTemplate()` додатка, яку буде позначено для наступного використання &Qt; Designer (типове значення: порожнє).

`ConstructorArgs`

- Аргументи, які слід передати конструктору класу, вказаного за допомогою `ImplClass`; ці значення слід вказувати у дужках (типове значення: `(parent)`). Єдиною гарантовано доступною змінною є `parent`, тобто батьківський об’єкт `QWidget`, переданий &Qt; Designer.

  Цей запис буде проігноровано, якщо встановлено значення для `CreateWidget`.

`CreateWidget`

- Код, потрібний для створення екземпляра віджета (типове значення: використовувати `new` для створення екземпляра класу, вказаного записом `ImplClass`, передавати аргументи, вказані за допомогою `ConstructorArgs`). Див. опис записів `ImplClass` та `ConstructorArgs`.

`DomXML`

- Опис інтерфейсу користувача віджета у форматі XML (типове значення: типовий опис, створений на основі заголовків додатків &Qt; Designer).

`Group`

- Група, у якій віджет буде показано у &Qt; Designer (типове значення: значення запису `DefaultGroup` у розділі `[Global]`).

`IconName`

- Файл зображення або назва стандартної піктограми, яку слід використовувати як піктограму для цього віджета у списку віджетів &Qt; Designer (типове значення: файл PNG, назва якого збігається з назвою розділу без подвійних двокрапок, розташований у каталозі pics вбудованого файла ресурсів; приклад: `:/pics/Foo.png` у розділі `[Foo]` або `:/pics/FooBar.png` у розділі `[Foo::Bar]`).

`ImplClass`

- Клас, який слід використовувати для створення екземпляра віджета для використання у &Qt; Designer (типове значення: назва розділу). Зауважте, що насправді це може бути не той клас, який було б створено остаточною програмою: той клас визначається у `DomXML`.

  Цей запис буде проігноровано, якщо встановлено значення для `CreateWidget`.

`IncludeFile`

- Файл заголовків, який слід включити для використання цього віджета (типове значення: написана малими літерами назва розділу без двокрапок з дописаним «.h»; приклад: `foo.h` у розділі `[Foo]` або `foobar.h` у розділі `[Foo::Bar]`).

`IsContainer`

- Визначає, чи містить цей віджет інші віджети (типове значення: `false`).

`ToolTip`

- Підказка, яку буде показано у відповідь на затримування вказівника миші на віджеті у списку віджетів &Qt; Designer (типове значення: назва розділу з дописуванням « Widget»; приклад: `Foo Widget` у розділі `[Foo]`).

`WhatsThis`

- Текст підказки «Що це?», пов’язаної з віджетом у &Qt; Designer (типове значення: назва розділу з дописаним « Widget»; приклад: `Foo Widget` у розділі `[Foo]`).

## Приклади

Найпростіший файл опису може виглядати так:

    [Foo]
    ToolTip=Displays foos
    [Bar]
    ToolTip=Bar editor

Зауважте, що у кожному класі має бути принаймні один встановлений ключ (у нашому прикладі використано ключ `ToolTip`), інакше запис класу буде проігноровано.

Зазвичай, виникає потреба у зміні принаймні видимого користувачем тексту, тобто записів `ToolTip`, `WhatsThis` та `Group`. Крім того, варто також визначити назву додатка, щоб запобігти можливим конфліктам символів і не ускладнювати роботу засобів діагностики (самої програми та особи, яка шукає вади):

    [Global]
    PluginName=FooWidgets
    DefaultGroup=Display

    [Foo]
    ToolTip=Displays bears
    WhatsThis=An image widget that displays dancing bears

    [Bar]
    ToolTip=Bar editor
    WhatsThis=An editor interface for bars for bears
    Group=Editing

Якщо у вашій програмі використовуються окремі простори назв для різних класів або додаткові параметри, які слід передавати конструкторам, доведеться створити складніший файл. Приклад:

    [Global]
    PluginName=FooWidgets
    DefaultGroup=Foo

    [Foo::Bar]
    ToolTip=Displays bars
    WhatsThis=A widget that displays bars in a particular way
    IncludeFile=foo/bar.h
    IconName=:/previews/bar.png

    [Foo::Baz]
    IncludeFile=foo/baz.h
    ConstructorArgs=(Foo::Baz::SomeOption, parent)
    Group=Foo (Special)
    IsContainer=true
    IconName=:/previews/baz.png

Іноді, у дуже складних віджетах потрібна особлива реалізація «класу попереднього перегляду» для використання у &Qt; Designer; це може бути підклас справжнього віджета, лише з деякими додатковими налаштуваннями, або зовсім відмінна від нього реалізація.

    [Global]
    Includes=foopreviews.h

    [FancyWidget]
    ImplClass=FancyWidgetPreview

## Прочитайте також

https://doc.qt.io/qt-5/designer-creating-custom-widgets.html

- Документація з &Qt; Designer щодо створення додатків для нетипових віджетів.

## Вади

Для повідомлення про вади, будь ласка, скористайтеся системою стеження за вадами &kde;, не надсилайте електронних листів безпосередньо авторам.