3.4 Менеджер панелей (Panel Manager)

Специфікація BTRON3 (Український переклад) | Розділ 7: Графічна оболонка (GUI Shell)

Менеджер панелей забезпечує відображення та управління діалоговими панелями — спеціальними вікнами, що захоплюють фокус введення для взаємодії з користувачем: панелі помилок, запити підтвердження, параметри налаштування, вибір файлів.

Панель захоплює введення при відкритті і повертає фокус попередньому вікну при закритті. Вона може бути вкладеною (nested): нова панель відкривається поверх попередньої.

3.4.1.2 Структури даних панелі

Тип ID панелі

typedef W   PNID;   /* ID панелі */

Типи елементів панелі (itype)

#define NULL_ITEM   0   /* Відсутній */
#define PTR_ITEM    1   /* Вказівник */
#define PICT_ITEM   2   /* Піктограма */
#define PAT_ITEM    3   /* Патерн */
#define BMAP_ITEM   4   /* Бітова карта */
#define FIG_ITEM    5   /* Фігура */
#define TEXT_ITEM   6   /* Рядок тексту (1 рядок) */
#define PARTS_ITEM  7   /* Елемент управління (Parts) */

#define ACT_ITEM    0x80    /* Активний елемент (OR до типу) */
#define BLT_TEXT    0x40    /* Bullet-текст */
#define ATR_TEXT    0x20    /* Текст з атрибутами (OR до типу) */

Елемент панелі (PNL_ITEM)

typedef struct pnl_item {
    UW      itype;  /* Тип елемента */
    UW      info;   /* Різна інформація */
    RECT    ir;     /* Область відображення */
    W       desc;   /* Внутрішній дескриптор (заповнює менеджер) */
    W       dnum;   /* Номер даних */
    H      *ptr;    /* Вказівник на дані */
} PNL_ITEM;

Панель (PANEL)

typedef struct panel {
    UW      oframe;     /* Атрибути зовнішньої рамки */
    UW      iframe;     /* Атрибути внутрішньої рамки */
    W       bgpat;      /* Номер патерну фону */
    RECT    r;          /* Область відображення */
    W       defsw;      /* Номер Default Switch (кнопка за замовчуванням) */
    W       nitem;      /* Кількість елементів */
    PNL_ITEM *item;     /* Вказівник на масив елементів */
} PANEL;

3.4.1.3 Позиціювання панелі

Параметр позиції p у функціях панелі:

p = NULL — позиція за визначенням у даних панелі.
p->x = 0x8000 — горизонтальне центрування на екрані.
p->y = 0x8000 — вертикальне центрування на екрані.

Дані PANEL залишаються у використанні до закриття — не звільняти до виклику pdel_pnl(). Невірні номери патернів замінюються на значення за замовчуванням.

3.4.1.4 Обробка подій панелі

(1): Прикладна програма сама зчитує події через wget_evt(NOMSG) і обробляє за допомогою Parts Manager.
(2): Використання pact_pnl() — менеджер автоматично обробляє події і повертає результат.

Зазвичай метод (2); метод (1) — для спеціальної обробки.

3.4.3 Системні виклики Менеджера панелей

При помилці повертається від'ємний код; при успіху — «0» або «+».

pcre_pnl

Create Panel

Створення та відображення панелі

【Синтаксис / Прототип】

PNID    pcre_pnl(PANEL *pnl, PNT *p)

【Параметри】

PANEL  *pnl     Дані визначення панелі
PNT    *p       Абсолютна координата лівого верхнього кута (NULL = за визначенням)

【Значення, що повертається】

>= 0    ID панелі (PNID > 0)
 < 0    Помилка (Код помилки)

【Детальний опис】

Створює панель за даними pnl і відображає у позиції p. Панель захоплює фокус введення. Якщо поточний процес не є активним — попереднє активне вікно отримує EV_INACT, після чого відкривається панель. При закритті фокус повертається попередньому вікну і надсилається EV_SWITCH. Дані pnl залишаються у використанні — не звільняти до закриття.

【Коди помилок】

EX_ADR  : Недопустима адреса pnl або p.
EX_NOSPC: Нестача пам'яті.
EX_PAR  : Неприпустимий вміст pnl.
EX_SAVE : Нестача пам'яті для збереження образу (вкладені панелі).

popn_pnl

Open Panel from Data Box

Створення панелі з Data Box

【Синтаксис / Прототип】

PNID    popn_pnl(W dnum, PNT *p)

【Параметри】

W       dnum    Номер даних типу PANEL_DATA у Data Manager
PNT    *p       Позиція (NULL = за визначенням)

【Значення, що повертається】

>= 0    ID панелі (PNID)
 < 0    Помилка (Код помилки)

【Детальний опис】

Аналог pcre_pnl(), але дані панелі беруться з Data Box типу PANEL_DATA за номером dnum. Поведінка ідентична pcre_pnl().

【Коди помилок】

EX_DNUM : Дані (dnum) не зареєстровані у Data Manager.
EX_NOSPC: Нестача пам'яті.
EX_PAR  : Неприпустимий вміст.
EX_SAVE : Нестача пам'яті для збереження образу (вкладені панелі).

pdel_pnl

Delete Panel

Закриття та видалення панелі

【Синтаксис / Прототип】

ERR     pdel_pnl(W pnid, W opt)

【Параметри】

W   pnid    ID панелі
W   opt     0 = звичайне закриття; != 0 = примусове

【Значення, що повертається】

= 0     Успішне виконання
< 0     Помилка (Код помилки)

【Детальний опис】

Закриває та видаляє панель pnid. Відновлює образ екрана під панеллю. Повертає фокус попередньому вікну і надсилає EV_SWITCH (якщо EV_INACT був надісланий при відкритті).

【Коди помилок】

EX_PNID : Панель (pnid) не існує.

pact_pnl

Activate Panel (Standard Event Loop)

Стандартна обробка подій панелі

【Синтаксис / Прототип】

W   pact_pnl(W pnid, WEVENT *ev, W *item, W *val)

【Параметри】

W       pnid    ID панелі
WEVENT *ev      Буфер для поточної події (або NULL)
W      *item    Буфер для номера активованого елемента (або NULL)
W      *val     Буфер для значення елемента (або NULL)

【Значення, що повертається】

= 0     Активовано елемент (*item = номер, *val = значення)
= 1     Подія поза панеллю (повернута у *ev; обробити окремо)
= 2     Подія оброблена внутрішньо (продовжити цикл)
< 0     Помилка (Код помилки)

【Детальний опис】

Отримує і обробляє одну подію стосовно панелі pnid. Прикладна програма викликає у циклі до повернення «0» або «1»:

«0» — активовано елемент (кнопка тощо); *item = номер, *val = значення.
«1» — подія поза панеллю (наприклад EV_MENU); обробити окремо.
«2» — оброблено внутрішньо; продовжити цикл.

【Коди помилок】

EX_ADR  : Недопустима адреса ev, item або val.
EX_PNID : Панель (pnid) не існує.

pget_itm

Get Panel Item Value

Отримання значення елемента панелі

【Синтаксис / Прототип】

W   pget_itm(W pnid, W num)

【Параметри】

W   pnid    ID панелі
W   num     Номер елемента (1..nitem)

【Значення, що повертається】

>= 0    Поточне значення (залежить від типу елемента)
 < 0    Помилка (Код помилки)

【Детальний опис】

Повертає поточне значення елемента num. Для перемикача — 0/1; для числового поля — числове значення; для тексту — кількість символів.

【Коди помилок】

EX_PAR  : Неприпустимий num.
EX_PNID : Панель (pnid) не існує.

pset_itm

Set Panel Item Value

Встановлення значення елемента панелі

【Синтаксис / Прототип】

W   pset_itm(W pnid, W num, W val)

【Параметри】

W   pnid    ID панелі
W   num     Номер елемента (1..nitem)
W   val     Нове значення

【Значення, що повертається】

>= 0    Попереднє значення
 < 0    Помилка (Код помилки)

【Детальний опис】

Встановлює значення елемента num і оновлює відображення. Повертає попереднє значення.

【Коди помилок】

EX_PAR  : Неприпустимий num або val.
EX_PNID : Панель (pnid) не існує.

psel_box

Select List Box Item

Вибір елемента зі списку панелі

【Синтаксис / Прототип】

W   psel_box(W pnid, W num, W sel)

【Параметри】

W   pnid    ID панелі
W   num     Номер елемента-списку
W   sel     Індекс вибраного рядка (0..N-1; -1 = зняти вибір)

【Значення, що повертається】

>= 0    Попередній вибраний індекс
 < 0    Помилка (Код помилки)

【Детальний опис】

Встановлює вибраний рядок у елементі-списку і оновлює відображення. Повертає попередній вибраний індекс. При sel = -1 — скасовує вибір.

【Коди помилок】

EX_PAR  : Неприпустимий num або sel.
EX_PNID : Панель (pnid) не існує.

pget_gid

Get Drawing Environment ID

Отримання ID середовища малювання панелі

【Синтаксис / Прототип】

GID pget_gid(W pnid)

【Параметри】

W   pnid    ID панелі

【Значення, що повертається】

>= 0    ID середовища малювання (GID)
 < 0    Помилка (Код помилки)

【Детальний опис】

Повертає GID середовища малювання панелі для безпосереднього малювання поверх неї. Після малювання необхідно відновити всі змінені параметри середовища — інакше поведінка панелі непередбачувана.

【Коди помилок】

EX_PNID : Панель (pnid) не існує.

pact_err

Display Standard Error Panel

Відображення стандартної панелі помилки

【Синтаксис / Прототип】

W   pact_err(W kind, TC *arg1, TC *arg2, TC *arg3)

【Параметри】

W   kind    Номер даних PANEL_DATA (|kind| >= 1000; від'ємне = -kind)
TC *arg1    Рядок-замінник 1 (або NULL)
TC *arg2    Рядок-замінник 2 (або NULL)
TC *arg3    Рядок-замінник 3 (або NULL)

【Значення, що повертається】

>= 0    Зміщення натиснутої кнопки від Default Switch (0 = Default Switch)
 < 0    Помилка (Код помилки)

【Детальний опис】

Відображає стандартну панель помилки з даних типу PANEL_DATA номер kind. Стандартні панелі мають номер |kind| >= 1000. При kind < 0 — номер = -kind.

Перші до 3 текстових елементів замінюються рядками arg1..arg3 (нетекстовий елемент зупиняє заміну):

    Елемент 1 текстовий → arg1; елемент 2 текстовий → arg2; елемент 3 текстовий → arg3

Блокується до натискання кнопки. Default Switch обов'язковий. Повертає зміщення натиснутої кнопки від Default Switch (0..N-1).

Приклад: Default Switch = пункт 4, пункти 4..7 — кнопки. Натискання пункту 6 → повертає 2.

【Коди помилок】

EX_ADR  : Недопустима адреса arg1, arg2 або arg3.
EX_PAR  : -1000 < kind < 1000; дані не зареєстровані; Default Switch не визначений;
          або є PARTS_ITEM з меншим номером за Default Switch.
EX_SAVE : Нестача пам'яті для образу (вкладені панелі, kind > 0).

pdsp_msg

Display System Message

Виведення повідомлення у системній панелі

【Синтаксис / Прототип】

W   pdsp_msg(TC *msg)

【Параметри】

TC *msg     Рядок повідомлення (NULL = лише очистити)

【Значення, що повертається】

>= 0    Кількість відображених символів (без відсічених)
 < 0    Помилка (Код помилки)

【Детальний опис】

Виводить msg у системній панелі повідомлень (статусний рядок), замінюючи попереднє. При msg = NULL — лише очищає. Символи поза зоною відсікаються. Використовується системний шрифт за замовчуванням.

【Коди помилок】

EX_ADR  : Недопустима адреса msg.

pdsp_tim

Display Time in System Panel

Відображення часу та мовного режиму у системній панелі

【Синтаксис / Прототип】

ERR pdsp_tim(UW stat)

【Параметри】

UW  stat    Стан мета-клавіш (відповідає мовному/допоміжному режиму)

【Значення, що повертається】

>= 0    Успішне виконання
 < 0    Помилка (Код помилки)

【Детальний опис】

Оновлює мовний режим, допоміжний режим та поточний час у системній панелі повідомлень відповідно до stat. Оновлення відбувається лише при зміні стану. Виконується Менеджером вікон автоматично — звичайним програмам не потрібно.

【Коди помилок】

Відсутні.

pact_msg

Process System Message Panel Event

Обробка події системної панелі повідомлень

【Синтаксис / Прототип】

ERR pact_msg(WEVENT *ev)

【Параметри】

WEVENT *ev  Подія вікна (EV_NULL, EV_REDISP тощо)

【Значення, що повертається】

>= 0    Тип обробленої події
 < 0    Помилка (Код помилки)

【Детальний опис】

Обробляє подію ev для системної панелі повідомлень і оновлює її відображення. Виконується Менеджером вікон автоматично — звичайним програмам не потрібно.

【Коди помилок】

EX_ADR  : Недопустима адреса ev.