Приложения

Приложение А. Функции, константы и структуры RDS

А.5. Сервисные функции и макросы RDS

А.5.18. Системное меню и контекстное меню блока

А.5.18.8. rdsRegisterMenuItem – создать пункт системного меню RDS

Функция rdsRegisterMenuItem добавляет новый пункт в меню RDS «Система | Дополнительно».

  RDS_MENUITEM RDSCALL rdsRegisterMenuItemA(
    RDSCSTR Caption,  // Текст пункта меню (UTF8)
    DWORD Options,    // Флаги (RDS_MENU_*)
    int ShortCutKey,  // Код "горячей клавиши"
    DWORD ShiftFlags, // Флаги "горячей клавиши"(RDS_K*)
    int MenuFunc,     // Номер функции пункта меню
    int MenuData      // Данные пункта меню
  );
  RDS_MENUITEM RDSCALL rdsRegisterMenuItemW(
    RDSWCSTR Caption, // Текст пункта меню (UTF16)
    DWORD Options,    // Флаги (RDS_MENU_*)
    int ShortCutKey,  // Код "горячей клавиши"
    DWORD ShiftFlags, // Флаги "горячей клавиши"(RDS_K*)
    int MenuFunc,     // Номер функции пункта меню
    int MenuData      // Данные пункта меню
  );
  // Функция-псевдоним
  RDS_MENUITEM RDSCALL rdsRegisterMenuItem(
    RDSXCSTR Caption, // Текст пункта меню (кодировка по умолчанию)
    DWORD Options,    // Флаги (RDS_MENU_*)
    int ShortCutKey,  // Код "горячей клавиши"
    DWORD ShiftFlags, // Флаги "горячей клавиши"(RDS_K*)
    int MenuFunc,     // Номер функции пункта меню
    int MenuData      // Данные пункта меню
  );

Тип указателя на эту функцию

RDS_MhSDwIDwII (для UTF8) или RDS_MhWsDwIDwII (для UTF16)

Параметры

Caption (RDSCSTR, RDSWCSTR, RDSXCSTR)

Указатель на строку с текстом пункта меню – этот текст пользователь увидит в самом меню.

Options (DWORD)

Один или несколько объединенных битовым ИЛИ флагов, задающих параметры пункта меню:

RDS_MENU_DISABLED	Выбор пункта меню будет запрещен, пункт будет изображаться серым цветом.
RDS_MENU_CHECKED	Слева от текста пункта меню будет находиться галочка.
RDS_MENU_HIDDEN	Пункт меню будет невидимым (скрытым от пользователя).
RDS_MENU_SHORTCUT	У пункта меню будет «горячая клавиша», определяемая параметрами ShortCutKey и ShiftFlags.
RDS_MENU_UNIQUECAPTION	Если пункт с текстом Caption уже есть в меню, новый пункт добавлен не будет.

ShortCutKey (int)

Код «горячей клавиши» пункта меню (только если Item – пункт системного, а не контекстного меню). Это одна из стандартных констант VK_*, используемых в Windows API.

ShiftFlags (DWORD)

Набор битовых флагов RDS_K*, указывающих на сочетание «горячей клавиши» ShortCutKey со служебными клавишами Ctrl, Alt и Shift.

MenuFunc (int)

Номер функции пункта меню – при выборе пункта пользователем RDS копирует это число в поле Function структуры RDS_MENUFUNCDATA без какой-либо обработки.

MenuData (int)

Данные пункта меню – при выборе пункта пользователем RDS копирует это число в поле MenuData структуры RDS_MENUFUNCDATA без какой-либо обработки.

Возвращаемое значение

Уникальный идентификатор созданного пункта меню или NULL при невозможности добавления этого пункта.

Примечания

Эта функция создает новый пункт в системном меню RDS и возвращает его идентификатор, который можно использовать в других сервисных функциях, работающих с меню. Созданный пункт будет находиться в меню до тех пор, пока он не будет удален функцией rdsUnregisterMenuItem, или до тех пор, пока от создавшего его блока не будет отключена модель.

Добавленный пункт будет иметь текст Caption, его внешний вид будет определяться флагами в параметре Options, с пунктом будет связана пара целых чисел (MenuFunc,MenuData). При выборе этого пункта пользователем модель блока будет вызвана для реакции на событие RDS_BFM_MENUFUNCTION, и в ее параметре ExtParam будет передан указатель на структуру RDS_MENUFUNCDATA, в полях которой будут записаны числа, связанные с выбранным пунктом меню.

Пример

Пример использования функции rdsRegisterMenuItem приведен в §2.12.7 руководства программиста.

См. также

RDS_BFM_MENUFUNCTION, RDS_MENUFUNCDATA, rdsChangeMenuItem, rdsSetMenuItemOptions, rdsEnableMenuItem, rdsUnregisterMenuItem.