Функция AppendMenuA (winuser.h)

Статья
11/20/2024

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

Синтаксис

BOOL AppendMenuA(
  [in]           HMENU    hMenu,
  [in]           UINT     uFlags,
  [in]           UINT_PTR uIDNewItem,
  [in, optional] LPCSTR   lpNewItem
);

Параметры

[in] hMenu

Тип: HMENU

Дескриптор в строке меню, раскрывающемся меню, подменю или контекстном меню для изменения.

[in] uFlags

Тип: UINT

Управляет внешним видом и поведением нового элемента меню. Этот параметр может быть сочетанием следующих значений.

Ценность	Значение
MF_BITMAP 0x000000004L	Использует растровое изображение в качестве элемента меню. Параметр lpNewItem содержит дескриптор растрового изображения.
MF_CHECKED 0x000000008L	Поместите флажок рядом с элементом меню. Если приложение предоставляет растровые изображения флажка (см. SetMenuItemBitmaps, этот флаг отображает растровое изображение флажка рядом с элементом меню.
MF_DISABLED 0x000000002L	Отключает элемент меню, чтобы его нельзя было выбрать, но флаг не серо.
MF_ENABLED 0x000000000L	Включает элемент меню, чтобы его можно было выбрать, и восстанавливает его из его серого состояния.
MF_GRAYED 0x000000001L	Отключает элемент меню и серый цвет, чтобы его нельзя было выбрать.
MF_MENUBARBREAK 0x000000020L	Функции, аналогичные флагу MF_MENUBREAK для строки меню. В раскрывающемся меню, подменю или контекстном меню новый столбец отделяется от старого столбца вертикальной линией.
MF_MENUBREAK 0x000000040L	Помещает элемент в новую строку (для строки меню) или в новый столбец (для раскрывающегося меню, подменю или контекстного меню) без разделения столбцов.
MF_OWNERDRAW 0x00000100L	Указывает, что элемент является элементом, нарисованным владельцем. Перед первым отображением меню окно, которое владеет меню, получает сообщение WM_MEASUREITEM для получения ширины и высоты элемента меню. Затем сообщение WM_DRAWITEM отправляется в процедуру окна владельца при каждом появлении элемента меню.
MF_POPUP 0x00000010L	Указывает, что элемент меню открывает раскрывающееся меню или подменю. Параметр uIDNewItem указывает дескриптор раскрывающегося меню или подменю. Этот флаг используется для добавления имени меню в строку меню или элемента меню, открывающего подменю в раскрывающееся меню, подменю или контекстное меню.
MF_SEPARATOR 0x00000800L	Рисует горизонтальную линию деления. Этот флаг используется только в раскрывающемся меню, подменю или контекстном меню. Строка не может быть серой, отключенной или выделенной. Параметры lpNewItem и uIDNewItem игнорируются.
MF_STRING 0x000000000L	Указывает, что элемент меню является текстовой строкой; параметр lpNewItem — это указатель на строку.
MF_UNCHECKED 0x000000000L	Не помещать флажок рядом с элементом (по умолчанию). Если приложение предоставляет растровые изображения флажка (см. SetMenuItemBitmaps), этот флаг отображает четкое растровое изображение рядом с элементом меню.

[in] uIDNewItem

Тип: UINT_PTR

Идентификатор нового элемента меню или, если параметр uFlags имеет значение MF_POPUP, дескриптор раскрывающегося меню или подменю.

[in, optional] lpNewItem

Тип: LPCTSTR

Содержимое нового элемента меню. Интерпретация lpNewItem зависит от того, включает ли параметр uFlags следующие значения.

Ценность	Значение
MF_BITMAP 0x000000004L	Содержит дескриптор растрового изображения.
MF_OWNERDRAW 0x00000100L	Содержит предоставленное приложением значение, которое можно использовать для поддержания дополнительных данных, связанных с элементом меню. Значение находится в элементе itemData структуры, на которую указывает параметр lParamWM_MEASUREITEM или WM_DRAWITEM сообщения, отправляемого при создании меню или его появлении.
MF_STRING 0x000000000L	Содержит указатель на строку, завершаемую значением NULL.

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

Тип: BOOL

Если функция выполнена успешно, возвращаемое значение ненулевое. Если функция завершается ошибкой, возвращаемое значение равно нулю. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.

Замечания

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

Чтобы получить акселераторы клавиатуры для работы с растровым изображением или элементами меню, нарисованным владельцем, владелец меню должен обработать сообщение WM_MENUCHAR. Дополнительные сведения см. в меню Owner-Drawn и WM_MENUCHAR сообщения.

Следующие группы флагов нельзя использовать вместе:

MF_BITMAP, MF_STRINGи MF_OWNERDRAW
MF_CHECKED и MF_UNCHECKED
MF_DISABLED, MF_ENABLEDи MF_GRAYED
MF_MENUBARBREAK и MF_MENUBREAK

Примеры

Пример см. в статье Добавление строк и графов в меню.

Заметка

Заголовок winuser.h определяет AppendMenu как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	winuser.h (включая Windows.h)
библиотеки	User32.lib
DLL	User32.dll
набор API	ext-ms-win-ntuser-menu-l1-1-0 (представлено в Windows 8)