Спецификации для пользовательских элементов управления

Чтобы использовать пользовательские элементы управления в Designer, необходимо скомпилировать их в динамическую библиотеку.

Скрипт компиляции можно найти по ссылке: https://github.com/zlgopen/awtk-widget-number-label/blob/master/src/SConscript

1. Структура каталогов

design — здесь хранятся исходные ресурсы примеров кода, которые можно открыть и отредактировать в Designer.
res — здесь хранятся ресурсы, необходимые для запуска примеров кода. Они создаются с помощью Designer или скриптом scripts/update_res.py.
bin — здесь находятся динамические библиотеки и исполняемые файлы.
lib — здесь находятся статические библиотечные файлы.
demos — здесь хранятся примеры кода.
idl — здесь находится сгенерированный файл IDL.
scripts — здесь находятся скрипты, генерирующие ресурсы.
src — здесь хранится исходный код элементов управления. Каждый элемент управления находится в отдельном каталоге.
tests — здесь находится тестовый код.

Пример:

├─design
│  └─default
├─res
│  └─assets
│       └─default
├─bin
├─lib
├─demos
├─docs
├─idl
├─scripts
├─src
│  └─number_label
└─tests

Полный пример можно посмотреть в number-label.

2. Спецификации именования

2.1 Тип элемента управления

Имя типа элемента управления состоит из строчных английских слов, соединённых подчёркиванием.

Например:

#define WIDGET_TYPE_NUMBER_LABEL "number_label"

Тип элемента управления используется для его регистрации, чтобы его можно было использовать в XML UI-файлах.

Имя элемента управления должно отражать его функциональность.

2.2 Имя подкаталога

В src имя подкаталога соответствует имени типа элемента управления.

2.3 Имя файла

Заголовок файла: имя типа элемента управления + ".h".
Исходный файл: имя типа элемента управления + ".c".

2.4 Имя класса

Имя класса состоит из имени типа элемента управления и "_t".

Например:

typedef struct _number_label_t {
  widget_t widget;
  ...
} number_label_t;

Пользовательские элементы управления могут иметь только widget_t в качестве родительского класса.

2.5 Имя функции

Имена функций-членов начинаются с имени типа элемента управления, за которым следует подчёркивание, и состоят из строчных слов.

Например:

/**
 * @method number_label_set_format
 * Устанавливает формат строки (используется для преобразования чисел с плавающей точкой в строки).
 * @annotation ["scriptable"]
 * @param {widget_t*} widget Объект элемента управления.
 * @param {const char*} format Формат строки.
 *
 * @return {ret_t} Возвращает RET_OK в случае успеха, иначе — ошибку.
 */
ret_t number_label_set_format(widget_t* widget, const char* format);

2.6 Имя свойства

Имена свойств состоят из строчных английских слов, соединённых подчёркиванием.

Имена свойств должны соответствовать именам свойств в XML UI-файлах.

Пример:

  /**
   * @property {char*} format
   * @annotation ["set_prop","get_prop","readable","persitent","design","scriptable"]
   *
   * Формат строки.
   *
   */
  char* format;

Если изменение определённого свойства вызывает событие EVT_VALUE_CHANGED, то свойство должно поддерживать доступ через WIDGET_PROP_VALUE.

Например, свойство password элемента управления «Жестовый пароль» доступно для ввода пользователем и изменяет значение при изменении пароля. В функциях get_prop/set_prop доступ к свойству password должен осуществляться через WIDGET_PROP_VALUE.

static ret_t gesture_lock_get_prop(widget_t* widget, const char* name, value_t* v) {
  gesture_lock_t* gesture_lock = GESTURE_LOCK(widget);
  return_value_if_fail(gesture_lock != NULL && name != NULL && v != NULL, RET_BAD_PARAMS);
  ret_t ret = RET_NOT_FOUND;

  if (tk_str_eq(name, GESTURE_LOCK_PROP_PASSWORD) || tk_str_eq(name, WIDGET_PROP_VALUE)) {
    value_set_str(v, gesture_lock->password);
    ret = RET_OK;
  }

  return ret;
}

2.7 Имя события

Если у элемента управления есть собственные события, они называются EVT, за которыми следуют заглавные английские слова, разделённые подчёркиванием.

Например:

/**
 * @event {pointer_event_t} EVT_LONG_PRESS
 * Событие длинного нажатия.
 */

2.8 Имя динамической библиотеки

Если в динамической библиотеке есть только один элемент управления, её имя совпадает с именем типа элемента управления. Если в динамической библиотеке несколько элементов управления, можно выбрать другое имя.

2.9 Имя функции регистрации элемента управления

Функция регистрации элемента управления отвечает за регистрацию элементов управления в динамических библиотеках.

Имя функции регистрации должно начинаться с имени динамической библиотеки, затем добавляться "_register". Функция не имеет параметров и возвращает ret_t.

Например:

/**
 * @method number_label_register
 * Регистрирует элемент управления числовым текстом.
 *
 * @annotation ["global"]
 *
 * @return {ret_t} Возвращает RET_OK в случае успеха, иначе — ошибку.
 */
ret_t number_label_register(void);

2.10 Имя функции получения поддерживаемых режимов рендеринга

Доступные режимы рендеринга включают OpenGL, AGGE-BGR565, AGGE-BGRA8888 и AGGE-MONO. По умолчанию поддерживаются все режимы, разделенные символом «|», но это можно изменить в зависимости от ситуации.

Имя функции получения поддерживаемых режимов рендеринга должно начинаться с имени динамической библиотеки, а затем добавляться "_supported_render_mode". Функция не имеет параметров и возвращает const char*.

Например:

/**
 * @method number_label_supported_render_mode
 * Получает поддерживаемые режимы рендеринга.
 *
 * @annotation ["global"]
 *
 * @return {const char*} Возвращает RET_OK в случае успеха, иначе — ошибку.
 */
const char* number_label_supported_render_mode(void);

3. Формат комментариев

Пользовательские элементы управления должны использовать стандартные комментарии AWTK. См. API Doc Format (api_doc.md).

4. Вспомогательные инструменты

AWTK предоставляет некоторые инструменты для создания IDL и таблиц экспорта символов динамических библиотек.

awtk/tools/idl_gen/index.js используется для генерации IDL.

Например:

node ../awtk/tools/idl_gen/index.js idl/idl.json src/

awtk/tools/dll_def_gen/index.js используется для создания таблицы экспорта символов динамической библиотеки.

Например:

node ../awtk/tools/dll_def_gen/index.js idl/idl.json src/number_label.def

Для использования этих инструментов необходимо установить nodejs.

5. Зависимость от версии AWTK

Можно настроить зависимость динамической библиотеки от конкретной версии AWTK в файле project.json проекта пользовательского элемента управления.

Например:

{
  ...
  "usesSdk": {
    "awtk:minSdkVersion": "20070",
    "awtk:maxSdkVersion": "20090",
    "awtk:targetSdkVersion": "20090"
  }
  ...
}

Параметр awtk:minSdkVersion является необязательным и указывает на минимальную совместимую версию.
Параметр awtk:maxSdkVersion является необязательным и указывает на максимальную совместимую версию.
Параметр awtk:targetSdkVersion является необязательным и указывает на оптимальную версию.

Номера версий соответствуют release_id в component.json выпущенных AWTK. Обратите внимание, что если явно не указано иное, предполагается совместимость со всеми версиями. Комментарий дополняется в следующем формате.

/**
...
 * ```xml
 * <!-- ui -->
 * 控件初始属性的 xml 描述（如果描述中包含子控件，会同时创建）
 * ```
...
 * ```xml
 * <!-- style -->
 * 控件默认样式的 xml 描述（如果描述中包含其它控тей的样式，会同时添加到 default.xml 样式文件）
 * ```
...
 */

Например:

/**
 * @class number_label_t
 * @parent widget_t
 * @annotation ["scriptable","design","widget"]
 * Числовой текстовый элемент управления.
 *
 * В xml используется тег «number\_label» для создания числового текстового элемента управления. Например:
 *
 * ```xml
 * <!-- ui -->
 * <number_label x="c" y="50" w="24" h="100" value="40" format="%.4lf" decimal_font_size_scale="0.5"/>
 * ```
 *
 * Можно использовать style для настройки внешнего вида элемента управления, например, размера и цвета шрифта и т. д. Например: 
 * 
 * ```xml
 * <!-- style -->
 * <number_label>
 *   <style name="default" font_size="32">
 *     <normal text_color="black" />
 *   </style>
 *   <style name="green" font_name="led" font_size="32">
 *     <normal text_color="green" />
 *   </style>
 * </number_label>
 * ```
 */

Дизайнер инициализирует свойства и стиль элемента управления на основе вышеуказанного описания, но игнорирует атрибуты x и y.

7. Значки в Designer

Если необходимо изменить значок пользовательского элемента управления в Designer, поместите значок в указанное место.

7.1 Значок библиотеки

Значок библиотеки указывает на значок, используемый для идентификации пользовательской библиотеки элементов управления или описания её функций на страницах «Выбор шаблона» или «Управление шаблонами» в Designer. Размер значка составляет 60*60 пикселей.

По умолчанию используется docs/images/widget_preview.png из пользовательской библиотеки элементов управления.

Если не указано иное, отображается пустое поле.

7.2 Значок в списке элементов управления

Значок в списке элементов управления указывает на значок данного элемента управления в списке элементов управления в Designer. Его размер составляет 48*48 пикселей.

По умолчанию используется docs/images/widget_list.png из пользовательской библиотеки элементов управления.

Если не указано иное, будет отображаться значок по умолчанию. Если пользовательская библиотека элементов управления содержит несколько элементов управления, можно использовать форму «widget_list_» + имя типа элемента управления для назначения отдельного значка элементу управления, например «widget_list_number_label.png».

7.3 Значок на панели объектов

Значок на панели объектов указывает на значок типа объекта, отображаемый слева от объекта в панели объектов в Designer. Его размер составляет 16*16 пикселей.

По умолчанию используется docs/images/widget_obj.png из пользовательской библиотеки элементов управления.

Если не указано иное, будет отображаться значок по умолчанию. Если пользовательская библиотека элементов управления содержит несколько элементов управления, можно использовать форму «widget_obj_» + имя типа элемента управления для назначения отдельного значка типу элемента управления, например «widget_obj_number_label.png».

8. Использование относительных путей для включения заголовочных файлов в каталоге src

Чтобы избежать необходимости устанавливать каталог include во время компиляции при использовании пользовательских библиотек элементов управления и улучшить взаимодействие с пользователем, требуется использовать относительные пути при включении заголовочных файлов в исходном коде.

Например, если number_label.h и number_label.c находятся в одном каталоге, то в number_label.c следует включить их следующим образом:

...
#include "number_label.h"
...

Если вы не используете относительный путь, пожалуйста, укажите каталог, который необходимо включить, в файле README.md пользовательской библиотеки элементов управления.

OSCHINA-MIRROR/zlgopen-awtk

Спецификации для пользовательских элементов управления

1. Структура каталогов

2. Спецификации именования

2.1 Тип элемента управления

2.2 Имя подкаталога

2.3 Имя файла

2.4 Имя класса

2.5 Имя функции

2.6 Имя свойства

2.7 Имя события

2.8 Имя динамической библиотеки

2.9 Имя функции регистрации элемента управления

2.10 Имя функции получения поддерживаемых режимов рендеринга

3. Формат комментариев

4. Вспомогательные инструменты

5. Зависимость от версии AWTK

7. Значки в Designer

7.1 Значок библиотеки

7.2 Значок в списке элементов управления

7.3 Значок на панели объектов

8. Использование относительных путей для включения заголовочных файлов в каталоге src

Опубликовать ( 0 )

Введение

Обновления

Участники

Недавние действия

OSCHINA-MIRROR/zlgopen-awtk .gitee-modal { min-width: 500px !important; } .gitee-modal .close { right: 0.6rem !important; }

Спецификации для пользовательских элементов управления

1. Структура каталогов

2. Спецификации именования

2.1 Тип элемента управления

2.2 Имя подкаталога

2.3 Имя файла

2.4 Имя класса

2.5 Имя функции

2.6 Имя свойства

2.7 Имя события

2.8 Имя динамической библиотеки

2.9 Имя функции регистрации элемента управления

2.10 Имя функции получения поддерживаемых режимов рендеринга

3. Формат комментариев

4. Вспомогательные инструменты

5. Зависимость от версии AWTK

7. Значки в Designer

7.1 Значок библиотеки

7.2 Значок в списке элементов управления

7.3 Значок на панели объектов

8. Использование относительных путей для включения заголовочных файлов в каталоге src

Опубликовать ( 0 )

Введение

Обновления

Участники

Недавние действия

OSCHINA-MIRROR/zlgopen-awtk