Funzione ModifyMenuA (winuser.h)

Articolo
03/13/2024

Modifica una voce di menu esistente. Questa funzione viene usata per specificare il contenuto, l'aspetto e il comportamento della voce di menu.

Nota La funzione ModifyMenu è stata sostituita dalla funzione SetMenuItemInfo . È comunque possibile usare ModifyMenu, se non sono necessarie funzionalità estese di SetMenuItemInfo.

Sintassi

BOOL ModifyMenuA(
  [in]           HMENU    hMnu,
  [in]           UINT     uPosition,
  [in]           UINT     uFlags,
  [in]           UINT_PTR uIDNewItem,
  [in, optional] LPCSTR   lpNewItem
);

Parametri

[in] hMnu

Tipo: HMENU

Handle del menu da modificare.

[in] uPosition

Tipo: UINT

Voce di menu da modificare, come determinato dal parametro uFlags .

[in] uFlags

Tipo: UINT

Controlla l'interpretazione del parametro uPosition e il contenuto, l'aspetto e il comportamento della voce di menu. Questo parametro deve includere uno dei valori necessari seguenti.

Valore	Significato
MF_BYCOMMAND 0x00000000L	Indica che il parametro uPosition fornisce l'identificatore della voce di menu. Il flag MF_BYCOMMAND è il valore predefinito se non viene specificato né il flag MF_BYCOMMAND né MF_BYPOSITION .
MF_BYPOSITION 0x00000400L	Indica che il parametro uPosition fornisce la posizione relativa in base zero della voce di menu.

Il parametro deve includere almeno uno dei valori seguenti.

Valore	Significato
MF_BITMAP 0x00000004L	Usa una bitmap come voce di menu. Il parametro lpNewItem contiene un handle per la bitmap.
MF_CHECKED 0x00000008L	Places un segno di spunta accanto all'elemento. Se l'applicazione fornisce bitmap di segno di spunta (vedere la funzione SetMenuItemBitmaps ), questo flag visualizza una bitmap selezionata accanto alla voce di menu.
MF_DISABLED 0x00000002L	Disabilita la voce di menu in modo che non possa essere selezionata, ma questo flag non lo grigio.
MF_ENABLED 0x00000000L	Abilita la voce di menu in modo che possa essere selezionata e ripristinarla dallo stato grigio.
MF_GRAYED 0x00000001L	Disabilita la voce di menu e la grigio in modo che non possa essere selezionata.
MF_MENUBARBREAK 0x00000020L	Funziona come il flag MF_MENUBREAK per una barra dei menu. Per un menu a discesa, sottomenu o menu di scelta rapida, la nuova colonna viene separata dalla colonna precedente in base a una riga verticale.
MF_MENUBREAK 0x00000040L	Places l'elemento in una nuova riga (per le barre dei menu) o in una nuova colonna (per un menu a discesa, sottomenu o menu di scelta rapida) senza separare le colonne.
MF_OWNERDRAW 0x00000100L	Specifica che l'elemento è un elemento disegnato dal proprietario. Prima che il menu venga visualizzato per la prima volta, la finestra che possiede il menu riceve un messaggio di WM_MEASUREITEM per recuperare la larghezza e l'altezza della voce di menu. Il messaggio WM_DRAWITEM viene quindi inviato alla procedura della finestra del proprietario ogni volta che deve essere aggiornato l'aspetto della voce di menu.
MF_POPUP 0x00000010L	Specifica che la voce di menu apre un menu a discesa o un sottomenu. Il parametro uIDNewItem specifica un handle nel menu a discesa o nel sottomenu. Questo flag viene usato per aggiungere un nome di menu a una barra dei menu o una voce di menu che apre un sottomenu a un menu a discesa, sottomenu o menu di scelta rapida.
MF_SEPARATOR 0x00000800L	Disegna una linea di divisione orizzontale. Questo flag viene usato solo in un menu a discesa, sottomenu o menu di scelta rapida. La riga non può essere disattivata, disabilitata o evidenziata. I parametri lpNewItem e uIDNewItem vengono ignorati.
MF_STRING 0x00000000L	Specifica che la voce di menu è una stringa di testo; il parametro lpNewItem è un puntatore alla stringa.
MF_UNCHECKED 0x00000000L	Non inserisce un segno di spunta accanto all'elemento (impostazione predefinita). Se l'applicazione fornisce bitmap di segno di spunta (vedere la funzione SetMenuItemBitmaps ), questo flag visualizza una bitmap chiara accanto alla voce di menu.

[in] uIDNewItem

Tipo: UINT_PTR

Identificatore della voce di menu modificata o, se il parametro uFlags ha il set di flag MF_POPUP , un handle nel menu a discesa o nel sottomenu.

[in, optional] lpNewItem

Tipo: LPCTSTR

Contenuto della voce di menu modificata. L'interpretazione di questo parametro dipende dal fatto che il parametro uFlags includa il flag MF_BITMAP, MF_OWNERDRAW o MF_STRING.

Valore	Significato
MF_BITMAP 0x00000004L	Handle bitmap.
MF_OWNERDRAW 0x00000100L	Valore fornito da un'applicazione usata per mantenere dati aggiuntivi correlati alla voce di menu. Il valore si trova nel membro itemData della struttura a cui fa riferimento il parametro lParam del WM_MEASUREITEM o WM_DRAWITEM messaggi inviati quando la voce di menu viene creata o la relativa aspetto viene aggiornata.
MF_STRING 0x00000000L	Puntatore a una stringa con terminazione null (impostazione predefinita).

Valore restituito

Tipo: BOOL

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Se ModifyMenu sostituisce una voce di menu che apre un menu a discesa o un sottomenu, la funzione elimina il menu a discesa precedente o il sottomenu e libera la memoria usata da esso.

Per consentire agli acceleratori di tastiera di usare le voci di menu bitmap o di disegno del proprietario, il proprietario del menu deve elaborare il messaggio di WM_MENUCHAR . Per altre informazioni, vedere Menu creati dal proprietario e il messaggio WM_MENUCHAR .

L'applicazione deve chiamare la funzione DrawMenuBar ogni volta che un menu cambia, se il menu è in una finestra visualizzata. Per modificare gli attributi delle voci di menu esistenti, è molto più veloce usare le funzioni CheckMenuItem e EnableMenuItem .

I gruppi di flag seguenti non possono essere usati insieme:

MF_BYCOMMAND e MF_BYPOSITION
MF_DISABLED, MF_ENABLED e MF_GRAYED
MF_BITMAP, MF_STRING, MF_OWNERDRAW e MF_SEPARATOR
MF_MENUBARBREAK e MF_MENUBREAK
MF_CHECKED e MF_UNCHECKED

Esempio

Per un esempio, vedere Impostazione dei tipi di carattere per Menu-Item stringhe di testo.

Nota

L'intestazione winuser.h definisce ModifyMenu come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winuser.h (include Windows.h)
Libreria	User32.lib
DLL	User32.dll
Set di API	ext-ms-win-ntuser-menu-l1-1-3 (introdotta in Windows 10, versione 10.0.14393)