Специфікація BTRON3 (Український переклад) | Розділ 7: Графічна оболонка (GUI Shell)
Повернутися до змісту розділу Графічної оболонки
Попередня сторінка: 3.1 Менеджер вікон (Повернутися)
Наступна сторінка: 3.3 Менеджер елементів інтерфейсу (Перейти)

3.2 Менеджер меню (Menu Manager)

3.2.1 Огляд підсистеми меню

3.2.1.1 Стандартне меню (Standard Menu)

Стандартне меню відображається у рядку меню вікна і складається з Головного меню (рядок вгорі: горизонтальні кнопки-вкладки) та Підменю (вертикальний список команд, що відкривається при виборі головного пункту).

Дані меню визначаються статично через структуру MENUITEM або через Data Box типу MENU_DATA. Менеджер меню компілює ці дані у внутрішні структури і присвоює MNID при реєстрації. Перед відображенням дані мають бути зареєстровані через mcre_men() або mopn_men().

3.2.1.2 Структура стандартного меню (MENUITEM)

typedef struct menuitem {
    UW  inact;      /* Прапор недоступних пунктів */
    UW  select;     /* Прапор вибраних пунктів */
    W   desc;       /* Внутрішній дескриптор (заповнюється менеджером) */
    W   dnum;       /* Номер даних списку пунктів */
    TC  *ptr;       /* Вказівник на список пунктів */
} MENUITEM;

inact — бітова маска: біт 0 = батьківський пункт, біти 1..N = підпункти. Якщо біт встановлено — пункт недоступний (сірий). select — аналогічно для стану «вибрано» (індикатор).

3.2.1.3 Атрибути відображення стандартного меню (MENUDISP)

typedef struct menudisp {
    UW      m_frame;    /* Ширина/патерн рамки головного меню */
    UW      s_frame;    /* Ширина/патерн рамки підменю */
    UW      m_bgpat;    /* Патерн фону головного меню */
    UW      s_bgpat;    /* Патерн фону підменю */
    UW      s_indpat;   /* Патерн індикатора */
    COLOR   m_chcol;    /* Колір тексту головного меню */
    COLOR   s_chcol;    /* Колір тексту підменю */
    COLOR   s_keycol;   /* Колір клавіатурних макросів у підменю */
} MENUDISP;

Поля m_bgpat, s_bgpat, s_indpat задаються номерами даних типу PAT_DATA; 0 = за замовчуванням. Поля кольорів < 0 = за замовчуванням.

3.2.1.4 Константи атрибутів пунктів меню

#define MC_LINE     0x1004  /* Роздільна лінія */
#define MC_KEY      0x10f0  /* Маска кількості клавіатурних макросів */
#define MC_IND      0x1100  /* Наявність індикатора */
#define MC_SEL      0x1200  /* Стан індикатора */

#define MC_KEY1     0x1010  /* 1 клавіатурний макрос */
#define MC_KEY2     0x1020  /* 2 клавіатурних макроси */
    ~
#define MC_KEY15    0x10f0  /* 15 клавіатурних макросів */

3.2.1.5 Константи позиції відображення меню

#define M_LASTPOS   0x0000  /* Початковий пункт = останній використаний головний */
#define M_FIXPOS    0x0002  /* Початковий пункт = другий головний пункт */

3.2.1.6 Константи зміни атрибутів пунктів (mset_itm / mchg_atr)

#define M_STAT      0   /* Не змінювати (лише отримати поточний стан) */
#define M_SEL       1   /* Встановити стан «вибрано» */
#define M_NOSEL     4   /* Скасувати стан «вибрано» */
#define M_ACT       8   /* Зробити пункт доступним */
#define M_INACT     2   /* Зробити пункт недоступним */

3.2.1.7 Узагальнене меню (Generic Menu / GMENU)

На відміну від стандартного, Узагальнене меню (Меню) є вільно позиціонованим контекстним popup-меню з довільними прямокутними зонами. Зони (r[32]) задаються програмно, і менеджер відображає пункти у вказаних областях.

Під час відображення всі інші операції малювання блокуються.

3.2.1.8 Структура узагальненого меню (GMENU)

typedef struct gmenu {
    UW      frame;      /* Атрибути рамки */
    UW      bgpat;      /* Патерн фону */
    UW      indpat;     /* Патерн індикатора */
    COLOR   chcol;      /* Колір тексту / роздільних рамок */
    RECT    area;       /* Загальна область відображення */
    UW      inact;      /* Прапор недоступних пунктів */
    UW      select;     /* Прапор вибраних пунктів */
    W       desc;       /* Внутрішній дескриптор */
    W       dnum;       /* Номер даних списку пунктів */
    TC      *ptr;       /* Вказівник на список пунктів */
    W       nitem;      /* Кількість пунктів (макс. 128) */
    RECT    r[32];      /* Область відображення кожного пункту (nitem штук) */
} GMENU;

area задає загальний прямокутник (лівий верхній кут зазвичай (0,0); фактична позиція задається при відображенні). nitem — кількість пунктів (1..128). r[i] — прямокутник i-го пункту у координатах відносно area.

Особливості атрибутів пунктів у GMENU:

3.2.2 Системні виклики Менеджера меню

Усі функції повертають від'ємний код при помилці, «0» або «+» при успіху.

mcre_men
Create Standard Menu
Реєстрація стандартного меню

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

MNID    mcre_men(MENUITEM *mi, MENUDISP *md)

【Параметри】

MENUITEM   *mi      Структура даних меню
MENUDISP   *md      Атрибути відображення (NULL = за замовчуванням)

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

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

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

Реєструє стандартне меню з даних mi та атрибутів відображення md. Повертає ID меню MNID для подальшого використання. Дані меню копіюються у внутрішні буфери менеджера, тому після реєстрації структура mi може бути звільнена. При завершенні процесу всі його меню автоматично видаляються, але рекомендується явне видалення через mdel_men().

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

EX_ADR  : Недопустима адреса mi або md.
EX_NOSPC: Нестача системної пам'яті.
EX_PAR  : Неприпустимий вміст mi або md.
mopn_men
Open Standard Menu from Data Box
Реєстрація стандартного меню з Data Box

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

MNID    mopn_men(W dnum, MENUDISP *md)

【Параметри】

W          dnum     Номер даних типу MENU_DATA у Data Manager
MENUDISP  *md       Атрибути відображення (NULL = за замовчуванням)

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

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

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

Аналог mcre_men(), але дані меню беруться з Data Box типу MENU_DATA за номером dnum. У решті функція ідентична mcre_men().

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

EX_DNUM : Дані (dnum) не зареєстровані у Data Manager.
EX_NOSPC: Нестача пам'яті.
EX_PAR  : Неприпустимий вміст даних.
mdel_men
Delete Standard Menu
Видалення стандартного меню

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

ERR     mdel_men(W mid)

【Параметри】

W   mid     ID меню (MNID)

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

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

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

Видаляє зареєстроване стандартне меню mid і звільняє пов'язані ресурси. При завершенні процесу меню видаляється автоматично, але явне видалення є кращою практикою.

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

EX_MID  : Меню (mid) не існує (або є не стандартним меню).
msel_men
Select Standard Menu Item
Відображення стандартного меню та вибір пункту

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

W   msel_men(W mid, PNT pos, W opt, WEVENT *evt)

【Параметри】

W       mid     ID меню
PNT     pos     Абсолютна координата початку відображення меню
W       opt     M_LASTPOS | M_FIXPOS — вибір початкового пункту
WEVENT *evt     Подія, що ініціювала відображення (EV_MENU)

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

>= 0    Номер вибраного пункту (1..N; 0 = нічого не вибрано)
 < 0    Помилка (Код помилки)

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

Відображає стандартне меню mid у позиції pos і очікує дії користувача (переміщення + відпускання вказівника). При виборі пункту — повертає його номер. При відсутності вибору — повертає 0.

opt визначає початковий головний пункт: M_LASTPOS — останній використаний, M_FIXPOS — другий пункт.

Під час роботи меню події EV_BUTDWN, EV_BUTUP, EV_KEYDWN, EV_KEYUP, EV_AUTKEY видаляються з черги. Інші події залишаються. Якщо не вдається зберегти образ екрана — після закриття всі вікна отримують запит перемальовування.

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

EX_ADR  : Недопустима адреса evt.
EX_MID  : Меню (mid) не існує.
EX_PAR  : Подія evt не є EV_MENU.
mget_itm
Get Menu Item Attribute
Отримання атрибутів пункту стандартного меню

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

W   mget_itm(W mid, W num)

【Параметри】

W   mid     ID меню
W   num     Номер пункту (0 = батьківський; 1..N = підпункти)

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

>= 0    Поточний атрибут пункту (комбінація M_SEL / M_INACT)
 < 0    Помилка (Код помилки)

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

Повертає поточний атрибут пункту num меню mid. Значення враховує як базовий список пунктів, так і прапори inact/select.

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

EX_MID  : Меню (mid) не існує.
EX_PAR  : Неприпустимий номер пункту num.
mset_itm
Set Menu Item Attribute
Зміна атрибутів пункту стандартного меню

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

W   mset_itm(W mid, W num, UW mode)

【Параметри】

W   mid     ID меню
W   num     Номер пункту (0 = батьківський; 1..N = підпункти)
UW  mode    M_STAT | M_SEL | M_NOSEL | M_ACT | M_INACT

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

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

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

Змінює атрибути (доступність, стан вибору) пункту num меню mid і повертає попередній стан. Базові коди атрибутів пункту не змінюються.

Значення mode:

M_STAT
Не змінювати (лише отримати поточний стан)
M_SEL
Встановити стан «вибрано» (індикатор)
M_NOSEL
Скасувати стан «вибрано»
M_ACT
Зробити пункт доступним
M_INACT
Зробити пункт недоступним

Для пунктів без індикатора (MC_IND = 0) M_SEL/M_NOSEL ігноруються, повертається 0 у полі M_SEL.

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

EX_MID  : Меню (mid) не існує.
EX_PAR  : Неприпустимий num або mode.
mchg_atr
Change Display Attributes
Зміна атрибутів відображення стандартного меню

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

ERR mchg_atr(W mid, MENUDISP *md)

【Параметри】

W          mid     ID меню
MENUDISP  *md      Нові атрибути відображення (NULL = скинути до за замовчуванням)

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

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

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

Змінює атрибути відображення (кольори, патерни) вже зареєстрованого меню mid. При md = NULL — скидає до системних значень за замовчуванням.

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

EX_ADR  : Недопустима адреса md.
EX_MID  : Меню (mid) не існує.
EX_PAR  : Неприпустимий вміст md.
mchg_dsp
Change Menu Display Data
Зміна даних відображення стандартного меню

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

ERR mchg_dsp(W mid, MENUITEM *mi)

【Параметри】

W          mid     ID меню
MENUITEM  *mi      Нові дані меню (NULL = перебудувати з поточних даних)

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

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

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

Оновлює внутрішні дані відображення меню mid. При mi != NULL — повністю замінює список пунктів. При mi = NULL — перебудовує відображення з поточних даних (наприклад, після зміни атрибутів через mset_itm()).

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

EX_ADR  : Недопустима адреса mi.
EX_MID  : Меню (mid) не існує.
EX_NOSPC: Нестача пам'яті.
EX_PAR  : Неприпустимий вміст mi.
mfnd_key
Find Menu Item by Key
Пошук пункту меню за клавіатурним макросом

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

W   mfnd_key(W mid, TC key)

【Параметри】

W   mid     ID меню
TC  key     Символ-ключ (клавіатурний макрос) для пошуку

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

>= 0    Номер пункту (0 = не знайдено)
 < 0    Помилка (Код помилки)

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

Шукає у меню mid пункт підменю, прив'язаний до символу клавіатурного макросу key. Якщо знайдено — повертає номер пункту; якщо ні — 0. Зазвичай використовується при обробці клавіатурних подій для «швидкого виклику» команд.

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

EX_MID  : Меню (mid) не існує.
mcre_gmn
Create Generic Menu
Реєстрація узагальненого меню

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

MNID    mcre_gmn(GMENU *gm)

【Параметри】

GMENU  *gm      Структура узагальненого меню

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

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

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

Реєструє узагальнене меню на основі структури GMENU. Повертає MNID. Дані копіюються у внутрішні структури менеджера. При завершенні процесу меню видаляється автоматично, але рекомендується явне видалення через mdel_gmn().

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

EX_ADR  : Недопустима адреса gm.
EX_NOSPC: Нестача пам'яті.
EX_PAR  : Неприпустимий вміст gm.
mopn_gmn
Open Generic Menu from Data Box
Реєстрація узагальненого меню з Data Box

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

MNID    mopn_gmn(W dnum)

【Параметри】

W   dnum    Номер даних типу GMENU_DATA у Data Manager

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

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

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

Аналог mcre_gmn(), але дані беруться з Data Box типу GMENU_DATA за номером dnum. У решті ідентична mcre_gmn().

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

EX_DNUM : Дані (dnum) не зареєстровані у Data Manager.
EX_NOSPC: Нестача пам'яті.
EX_PAR  : Неприпустимий вміст.
mdel_gmn
Delete Generic Menu
Видалення узагальненого меню

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

ERR mdel_gmn(W mid)

【Параметри】

W   mid     ID меню (MNID)

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

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

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

Видаляє зареєстроване узагальнене меню mid. При завершенні процесу — автоматичне видалення, але явне є кращою практикою.

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

EX_MID  : Меню (mid) не існує (або є не узагальненим меню).
msel_gmn
Select Generic Menu Item
Відображення узагальненого меню та вибір пункту

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

W   msel_gmn(W mid, PNT pos)

【Параметри】

W       mid     ID меню
PNT     pos     Абсолютна екранна координата (лівий верхній кут прямокутника меню)

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

>= 0    Номер вибраного пункту (1..128; 0 = нічого не вибрано)
 < 0    Помилка (Код помилки)

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

Відображає узагальнене меню mid, вирівнюючи лівий верхній кут до pos. Очікує дії вказівника: при відпусканні над активним пунктом — повертає його номер (1..128); при відпусканні поза пунктами — 0.

Під час роботи меню вказівник не змінюється — перед викликом рекомендується встановити форму «вказівний палець». Якщо не вдається зберегти образ екрана — після закриття надсилається запит перемальовування всіх вікон. Під час дії меню EV_BUTDWN, EV_BUTUP, EV_KEYDWN, EV_KEYUP, EV_AUTKEY видаляються з черги; інші події залишаються.

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

EX_MID  : Меню (mid) не існує.
mchg_gat
Change Generic Menu Item Attribute
Зміна атрибутів пункту узагальненого меню

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

W   mchg_gat(W mid, W num, UW mode)

【Параметри】

W   mid     ID меню
W   num     Номер пункту (1..128)
UW  mode    M_STAT | M_SEL | M_NOSEL | M_ACT | M_INACT

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

>= 0    Поточний атрибут пункту після зміни
 < 0    Помилка (Код помилки)

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

Змінює прапори доступності та вибору пункту num узагальненого меню mid. Повертає фактичний поточний стан (з урахуванням базових атрибутів пункту). Коди атрибутів у списку пунктів не змінюються.

Для пунктів без індикатора (MC_IND = 0) — M_SEL/M_NOSEL ігноруються; M_SEL у результаті завжди 0.

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

EX_MID  : Меню (mid) не існує (або є не узагальненим меню).
EX_PAR  : Неприпустимий num.
mchg_dtm
Change Menu Delay Time
Зміна часу затримки відгуку стандартного меню

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

W   mchg_dtm(W time)

【Параметри】

W   time    Час затримки у мілісекундах (< 0 = лише отримати поточне значення)

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

>= 0    Попереднє значення часу затримки

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

Встановлює час затримки відгуку між пунктами головного меню (час, протягом якого підменю не змінюється при русі вказівника). Повертає попереднє значення. При time < 0 — не змінює, лише повертає поточне значення. При старті системи встановлюється системний час за замовчуванням.

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

Відсутні.

Повернутися до змісту розділу Графічної оболонки
Попередня сторінка: 3.1 Менеджер вікон (Повернутися)
Наступна сторінка: 3.3 Менеджер елементів інтерфейсу (Перейти)