Связь Виджетов с PhAB

Эта глава обсуждает добавление заказных виджетов к PhAB, включая соображения по дизайну виджетов, а также следующие шаги:

Создание общедоступного объекта
Создание шаблона
Редактирование palette.def
Создание таблицы описания виджета

Убедитесь, что изменили Makefile вашего приложения так, чтобы он был связан с вашим новым виджетом. Включите заголовок виджета в глобальный заголовок приложения, определенный в диалоге Информация Запуска Приложения - Application Start-up Info.

соображения по дизайну виджетов

Этот раздел описывает проблемы, которые Вы должны рассмотреть, когда добавляете заказные виджеты к палитре виджетов PhAB:

Ресурсы с одиночным значением
Когда добавлять заказные виджеты к файлам палитры
Отображение вашего заказного виджета

Ресурсы с одиночным значением

PhAB имеет встроенные редакторы для обработки некоторых типов ресурсов с одиночным значением. Он также обеспечивает редакторы с несколькими значением для некоторых типов ресурса. Если Вы разрабатываете ваши ресурсы с использованием типов, поддерживаемых PhAB, разработчики будут способны использовать виджет в PhAB легко. Если Вы определите ресурсы, которые не имеют связанного редактора в PhAB, разработчики будут способны устанавливать и использовать эти ресурсы только через код приложения. Список в настоящее время поддерживаемых типов может быть найден в разделе "Создание таблицы описания виджета".

Когда добавлять заказные виджеты к файлам палитры

Когда Вы определяете класс виджета, то присваиваете ему номер виджета. Этот номер комбинируется с номером ресурса, чтобы создать ряд уникальных номеров ресурсов для виджета. Когда Вы добавляете виджет к палитре виджетов PhAB, то определяете эти значения ресурсов в файле палитры виджетов.

PhAB использует эти числа, когда сохраняет виджет в файлах модулей. Если Вы измените номер ресурса или номер виджета после того, как они использовались в приложении PhAB, то не сможете продолжить использовать старый виджет (определенный в модуле PhAB), потому что номера ресурсов больше не будут соответствовать. По этой причине, Вы должны добавлять виджеты к файлу палитры PhAB только, когда почти все функциональные возможности виджета были закончены, и номера ресурсов больше не будут изменяться.

Отображение вашего заказного виджета

Как описано в "Editing palette.def", позже в этой главе, Вы можете сообщить PhAB имя общедоступной библиотеки вашего виджета. Если PhAB сможет открыть эту библиотеку, он сможет отображать ваш заказной виджет, и Вы будете видеть результаты редактирования ресурсов виджета.

Если PhAB не сможет открыть вашу библиотеку виджета, Вы не сможете видеть изменение виджета визуально, когда делаете изменения в ресурсах. Виджет отобразится должным образом, когда Вы фактически скомпилируете, свяжите и проверите приложение.

Не забудьте включать файл заголовка виджета в заголовок приложения так, чтобы сгенерированный файл abmain.c знал о вашем виджете. Также, добавьте ваш виджет к списку объектов MYOBJ, определенный в файле indOfiles.

Создание общедоступного объекта

После того, как Вы создали ваш виджет, необходимо встроить его в общедоступный объект. Чтобы сделать это, скомпилируйте ваш исходный код подобно этому:

cc -shared -o libmy_wgt.so my_wgt.c -v -Wl,-hlibmy_wgt.so

Если Вы хотите сделать отладочную версию вашей библиотеки виджетов, добавьте к командной строке опцию компилятора -gdwarf-2 перед опцией -shared. Для получения дополнительной информации об параметрах компиляции смотрите qcc в QNX Справочнике по Утилитам - Utilities Reference.

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

Создание шаблона

Используйте PhAB для создания шаблонов вашего виджета. Для получения дополнительной информации, смотрите "Шаблоны - Templates" в главе Создание Виджетов в PhAB Руководства Программиста - Programmer's Guide Фотона.

Редактирование `palette.def`

Затем, отредактируйте файл /usr/photon/appbuilder/palette.def. Вы должны добавить некоторые строки, которые выглядят следующим образом:

l=PtWeb,<photon/PtWebClient.h>:ph
p=xpalette,Web Widgets

Первая строка это библиотечная строка, которая начинается с l=: Она состоит из:

Библиотека для загрузки (например PtWeb). PhAB добавляет lib перед именем, и .so в конец. В этом примере, фактическая библиотека libPtWeb.so. Определите имя общедоступного объекта, который Вы создали для вашего виджета. Если PhAB сможет открывать эту библиотеку, он сможет отобразить ваш виджет "живым", и Вы увидите результаты редактирования ресурсов немедленно.
Расположение файла заголовка для этого виджета (например <photon/PtWebClient.h>).
Любые библиотеки зависимостей для этого виджета, разделенные двоеточиями. В примере выше, есть только одна библиотека зависимостей ph.

Вторая строка идентифицирует файл палитры для этого виджета, и начинается с p=. Она состоит из:

Имя файла палитры; расширение .pal добавляется автоматически. В этом примере, имя файла палитры xpalette.pal.
Название группы для виджетов в этом файле палитры. В этом примере Web Widgets.

Создание таблицы описания виджета

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

Файл палитры может содержать любое число таблиц описания виджетов, но должен содержать по крайней мере одну. Имя вашего файла палитры должно оканчиваться расширением .pal (например mywidget.pal). Чтобы получить хорошая идею того, что должен содержать файл палитры, посмотрите /use/photon/appbuilder/ptpalette.pal file.

Вот пример таблицы описания виджета:

w=PwMenuWidget

h=4
PtWidget
PtBasic
PtContainer
PwMenuWidget

r=PW_LIST_DOWN,List Down Image,5001003,0,0,pixmap,NULL
r=PW_LIST_UP,List Up Image,5001004,0,0,pixmap,NULL
r=PW_SCROLL_DOWN,Scroll Down Image,5001005,0,0,pixmap,NULL
r=PW_SCROLL_UP,Scroll Up Image,5001006,0,0,pixmap,NULL
r=PW_SCROLL_LEFT,Scroll Left,5001007,0,0,pixmap,NULL
r=PW_SCROLL_RIGHT,Scroll Right, 5001008,0,0,pixmap,NULL

t=2
s=0xe906

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

Таблица описания виджета определяет следующие установки:

имя класса виджета (w=)
иерархия виджетов (h=)
список ресурсов (r=)
список обратных вызовов (c=, k=, e=)
наследуемые ресурсы и обратные вызовы (i=, n=)
базовый виджет (b=)
определение типа создания (t=)
стили курсора (s=)
значения по умолчанию (d=)

Имя класса виджета (`w=`)

Эта установка начинается с определения нового виджета:

w=имя_класса

Пример:

w=ShadowedBox

Не включайте пробелы перед или после знаков равно (=).

Когда PhAB сталкивается с установкой имени класса, он распределяет место в его внутреннем списке для виджета. Любые установки, найденные впоследствии, применяются к этому виджету, пока он не сталкиваются с новой установкой имени класса виджета.

Иерархия виджетов (`h=`)

Эта установка определяет иерархию виджетов:

h=число_уровней
наибольшее_имя_класса
[следующее_наибольшее_имя_класса]
...
имя_заказного_класса_виджета

Пример:

h=3
PtWidget
PtBasic
ShadowedBox

Установка h= указывает число уровней в иерархии. Она сопровождается именами иерархии класса виджета в порядке по убыванию наследования.

Установка иерархии виджета сообщает PhAB, который класс в иерархии виджета использовать, когда различные классы виджетов выбраны. Например, если Вы выбирете виджеты PtLabel и PtButton в одно и тоже время, Панель Управления PhAB должна показать вам ресурсы, которые относятся к обоим виджетам. PhAB делает это, идя по списку иерархии, пока не находит идентичное имя класса для обоих виджетов.

Список ресурсов (`r=`)

Если Вы хотите редактировать ресурсы в PhAB, то нуждаетесь или в записи r= (для новых ресурсов или наследуемых ресурсов с другим значением по умолчанию) или в записи i= (для наследуемых ресурсов) -- смотрите "Наследуемые ресурсы и обратные вызовы (i=, n=)" ниже.

Установка r= определения ресурс виджета:

r=явное_имя,описательное_имя,номер_ресурса,зарезервировано,указатель_выбора,тип,значение_по_умолчанию[,дополнительная_информация]
[дополнительная_информация_1
дополнительная_информация_2
...
дополнительная_информация_n]

Пример:

r=SBW_SHADOW_COLOR,Shadow Color,5000000,0,1,crgb,0x0
r=Pt_ARG_HORIZONTAL_ALIGNMENT,Horizontal Alignment,3000,0,1,short,2,3
Pt_LEFT,0
Pt_RIGHT,1
Pt_CENTER,2

Не создавайте записи для ресурсов Pt_ARG_POS и Pt_ARG_DIM. Все виджеты должны поддерживать их, так что PhAB обрабатывает их внутренне.

Параметры записи ресурса имеют следующие значения:

явное_имя

Допустимое C явное имя для обращения к этому ресурсу из кода приложения.

описательное_имя

Описательная версия явного имени, которое проще для понимания и занимает немного места (позволяя Панели Управления остаться небольшой).

номер_ресурса

Фактический номер ресурса (например Pt_USER(0)=5000000, Pt_USER(1)=5001000 и так далее -- Pt_RESOURCE(Pt_USER(2),5)=5002005).

зарезервировано

Всегда используйте значение 0.

указатель_выбора

Указывает, поддерживает ли этот ресурс мультивыбор. Значение 0 скроет ресурс, когда два или больше виджетов выбраны. Значение 1 откроет ресурсу.

тип

Указывает тип редактора, который PhAB должен использовать для этого ресурса. Допустимые типы:

pixmap: Поддерживает создание/модификацию структур PhImage_t.
bitmap: Используется только виджетом PtBitmap (не используйте это).
points: Используется внутренне PhAB для многосегментных строк. PhAB управляет этим типом ресурса, так что Вы можете использовать массив точек, обеспеченный PtGraphic.
list: Массив текстовых строк.
crgb: Значение цвета типа PgColor_t.
font: Спецификация шрифта (строка).
multi: Многострочная текстовая строка.
short: Числовое значение.
string: Однострочная текстовая строка.
datas: Однострочная текстовая строка (тип Alloc).
flag: Ресурс флага.
code: Указатель на функцию (смотрите Ресурсы указатели на функцию ниже).
double: Двойное значение.
float: Значение с плавающей точкой.

значение_по_умолчанию

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

дополнительная_информация

Это необязательное значение может использоваться, чтобы определить дополнительную информацию о ресурсе:

Список пар флагов для ресурсов типа flag; смотрите "Пары опций и флагов" ниже.
Список пар опций для ресурсов типа short; смотрите "Пары опций и флагов" ниже.
Прототип функции ресурсов типа code; смотрите "Ресурсы указатели на функцию" ниже.

Значение может быть определено как:

Число строк дополнительной информации после строки r=.
Если нет ниодной строки дополнительной информации, опустите дополнительная_информация. Не определяйте значение 0.
Класс виджета, для которого ресурс был определен ранее, и из которого Вы хотите скопировать дополнительную информацию. Это полезно, например, если описание или значение по умолчанию ресурса отличны для двух виджетов, но дополнительная информация одна и таже. Если ресурс один и тот же в обоих виджетах, более легко использовать i=запись, чтобы заставить виджет наследовать ресурс от другого.

Пары опций и флагов

Для ресурсов short и flag, дополнительная_информация определяет возможные значения. Каждая строка имеет форму:

описание,значение

где описание это текст, который PhAB отображает в редакторе, а значение соответствующее значение.

Ресурсы указатели на функцию

Для ресурса, который является указателем на функцию (например тип code), дополнительная_информация определяет число последующих строк, которые определяют прототип функции. Прототип должен содержать @ вместо имени функции, но без завершающей точки с запятой.

значение_по_умолчанию определяет код, который будет использоваться для тела функции всякий раз, когда PhAB генерирует функцию для ресурса. Если код вмещается в строку и не содержит запятых, Вы можете определить его непосредственно как значение_по_умолчанию. Иначе, поместите код в строки, которые следуют за прототипом функции, и установите значение_по_умолчанию в число строк кода.

Вот некоторые примеры:

r=ARG_SIMPLEFUNCTION,A function,5000001,5000001,1,return 0;,1
int @( void )

r=Pt_ARG_RAW_DRAW_F,Draw Function,24000,24000,1,code,1,1
void @( PtWidget_t *widget, PhTile_t *damage )
    PtSuperClassDraw( PtBasic, widget, damage );

r=Pt_ARG_LIST_BALLOON,Inflate Function,23031,23031,1,code,6,5
PtWidget_t *@(
        PtWidget_t *widget, PtWidget_t *parent,
        PhArea_t *area, PtListColumn_t const *column, int coln,
        const char *item, unsigned index, const char *font
        )
    return
        PtGenListCreateTextBalloon(
            widget, parent,
            PtGenListSetColumnBalloon( area, column ),
            item, coln, font
            );

Список обратных вызовов (`c=`, `k=`, `e=`)

Эти установки определяют обратные вызовы:

c|k|e=явное_имя,описательное_имя,номер_ресурса,зарезервировано

Пример:

c=Pt_CB_ACTIVATE,Activate,2009,0
k=Pt_CB_HOTKEY,Hotkey,1010,0
e=Pt_CB_RAW,Raw Event,1011,0

Фотон поддерживает три различных типа обратных вызовов. Это стандартные обратные вызовы виджета (c=), обратные вызовы горячей клавиши (k=) и необработанные обратные вызовы (e=). Удостоверитесь, что используете тип, который соответствует определению обратного вызова в виджете.

Параметры записей обратных вызовов идентичны и имеют следующие значения:

явное_имя: Допустимое явное С имя для обращения к этому ресурсу через код приложения.
описательное_имя: Описательная версия явного имени, которое проще для понимания и занимает мало места (позволяя Панели Управления оставаться небольшой).
номер_ресурса: Фактический номер ресурса (например Pt_USER(0)=5000000, Pt_USER(1)=5001000 и так далее -- Pt_RESOURCE(Pt_USER(2),5)=5002005).
зарезервировано: Всегда используйте значение 0.

Обратные вызовы могут также быть унаследованы от других виджетов. Смотрите "Наследуемые ресурсы и обратные вызовы (i=, n=)" ниже.

Наследуемые ресурсы и обратные вызовы (`i=`, `n=`)

Описания ресурсов могут быть разделены несколькими классами виджетов. Это сохраняет память во время выполнения, и помогает сохранить файлы палитры совместимыми (например, если новый флаг добавлен к ресурсу родительского класса, Вы не должны добавлять его к описанию каждого дочернего класса вручную).

Эти установки могут использоваться, чтобы наследовать определения ресурсов или обратных вызовов от виджета, определенного ранее:

i=виджет[,от[,к]]
n=виджет[,от[,к]]

i= строка копий ресурсов (определенных строкой r= или i=). n= строка копий обратных вызовов (определенных строками c=, k=, e= или i=).

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

Запись i= может использоваться только, если определения ресурсов для дочерних и родительских классов идентичны. Если имеются любые различия (например, дочерний класс переназначает значение по умолчанию), Вы будете должны использовать определение ресурса r= -- но дочерний класс может все еще наследовать любую дополнительную_информацию, которую родительский класс определил или унаследовал. Для получения дополнительной информации, смотрите "Список ресурсов (r=)".

Базовый виджет (`b=`)

Эта установка говорит PhAB использовать эмуляцию контейнера:

b=Container

Так как PhAB не может отображать ваш виджет непосредственно, он должен использовать заменяющий виджет вместо него. Если виджет не контейнер, и Вы не установили это значение, PhAB будет использовать виджет PtBasic, чтобы эмулировать ваш виджет. Если виджет контейнер, установите значение как показано выше и PhAB будет использовать PtContainer, чтобы эмулировать ваш виджет.

Определение типа создания (`t=`)

Эта установка определяет тип используемого режима создания:

t=число

Пример:

t=2

Определение типов сообщает PhAB, как этот виджет должен быть создан. Например, если t=1, PhAB автоматически создает виджет, как только пользователь щелкает в модуле. Это так, потому что тип 1 указывает виджет, который имеет предварительно установленный размер. Значение t=2 означает, что пользователь может изменять размеры при создании виджета.

Допустимые значения для число располагаются в диапазоне от 1 до 6 и имеют следующие значения:

Когда число равно:	Тип создания:
`1`	Предварительно установленный, изменяемый размер
`2`	Изменяемый размер при создании
`3`	Строка (2 точки)
`4`	Предварительно установленный, неизменяемый размер
`5`	Многоугольник (многоточечный)
`6`	Bezier (многоточечный с обработкой)

Для получения дополнительной информации, смотрите "Создание виджета - Creating a widget" в главе Создание Виджетов в PhAB Руководства Программиста - Programmer's Guide Фотона.

Стили курсоров (`s=`)

Эта установка определяет стиль курсора при создании виджета:

s=стартовый_стиль_курсора[,стиль_курсора_перетаскивания]

Пример:

s=0xe914,0xe914

Эта установка определяет вид курсора, когда виджет создается в PhAB. Значение, которое Вы выбираете для установки стиля курсора (s=), будет зависеть от значения, которое Вы определите для установки типа создания (t=). Для согласованности с другими виджетами в PhAB, мы рекомендуем, чтобы Вы назначали значения стиля курсора согласно таблице ниже:

Если тип создания:	Стиль курсора должен быть:
`t=1`	`s=0xe906`
`t=2`	`s=0xe914,0xe914`
`t=3`	`s=0xe906`
`t=4`	`s=0xe906`
`t=5`	`s=0xe906`
`t=6`	`s=0xe906`

Значения по умолчанию (`d=`)

Эта установка позволяет Вам давать виджету некоторые значения по умолчанию, чтобы переназначить значения по умолчанию, встроенные в виджет:

d=имя_класса,нет_определений_ресурсов
определение_1
определение_2
...
определение_n

Каждое определение состоит из трех значений:

номер_ресурса
тип_ресурса
значение_ресурса

Например:

// Пример изменяемого размера.
d=ShadowedBox,1
1005
dim
1,1

// Пример предварительной установки.
d=PtPrintSel,1
1005
dim
418,285

Каждое определение ресурса составлено из трех строк, и только простые типы ресурсов могут использоваться. В примере выше ресурс Pt_ARG_DIM (1005) установлен в 1 пиксел в высоту и в 1 пиксел в ширину. Это хорошая начальная точка для виджета с типом создания 2.

Вы должны всегда давать виджету значение по умолчанию и стартовые размеры. Если Вы не сделаете этого, то получите неожиданные результаты.

Если t=1 или t=4, установите ресурс dim в предварительно установленный размер. Если другое значение, установите dim в 1,1. Ресурс dim определен как "width,height" в пикселах.

Все мессаги сюда:yanich@inbox.ru